/ Hex Artifact Content
Login

Artifact e1db5dd6c7058352f0853a789a1c5822a83c32450f0c30fa83dd74169e1d2e61:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
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 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
10c0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
10d0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
10e0: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
10f0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1100: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
1110: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
1120: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
1130: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
1140: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1160: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
1170: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1180: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1190: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
11a0: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
11b0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
11c0: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
11d0: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
11e0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
11f0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1200: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1210: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
1220: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1230: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1240: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1250: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1270: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1280: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1290: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
12a0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
12b0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
12c0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
12d0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
12e0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
12f0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1300: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1310: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
1320: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1330: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1340: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1350: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1360: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1370: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1380: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1390: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
13a0: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
13b0: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
13c0: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
13d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13e0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13f0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1400: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1410: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
1420: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1430: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1450: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1460: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1470: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1480: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1490: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
14a0: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
14b0: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
14c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
14d0: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
14e0: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
14f0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1500: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1510: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1520: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1530: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
1540: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
1550: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
1560: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
1570: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1580: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1590: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
15a0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
15b0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
15c0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
15d0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
15e0: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
15f0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1600: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1610: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1620: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1630: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
1640: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
1650: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1660: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
1670: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1680: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1690: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
16a0: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
16b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
16c0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
16d0: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
16e0: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
16f0: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1700: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1710: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
1720: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
1730: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
1740: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
1750: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1760: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
1770: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1780: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1790: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
17a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
17b0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
17c0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
17d0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
17e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
17f0: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1800: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1810: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1820: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1830: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1840: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1850: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1860: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
1870: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1880: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1890: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
18a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
18b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
18c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
18d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
18e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
18f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1900: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1910: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1920: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1930: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1940: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1950: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1960: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1970: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1980: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1990: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
19a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
19b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
19c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
19d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
19e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
19f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1a00: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1a10: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1a20: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1a30: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1a40: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1a60: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1a70: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1a80: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1a90: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1aa0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1ab0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1ac0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1ad0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1ae0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1af0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1b00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1b10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1b30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1b40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1b50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1b60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1b70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1b80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1b90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ba0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1bb0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1bc0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1bd0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1be0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1bf0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1c00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1c10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1c20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1c30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1c40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1c50: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1c60: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c70: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1c80: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1c90: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1ca0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1cb0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1cc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1cd0: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1ce0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1cf0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1d00: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1d10: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1d20: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1d30: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1d40: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1d50: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1d60: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1d70: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1d80: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1da0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1db0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1dc0: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1dd0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1de0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1df0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1e00: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1e10: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1e20: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1e30: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1e40: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1e50: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1e60: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1e70: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1e80: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1e90: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1ea0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1eb0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
1ec0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
1ed0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
1ee0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
1ef0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
1f00: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1f10: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1f20: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1f30: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1f40: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1f50: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1f60: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1f70: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1f80: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1f90: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1fa0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
1fb0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
1fc0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
1fd0: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
1fe0: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
1ff0: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2000: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2010: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2020: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2030: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2040: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2050: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
2060: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
2070: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
2080: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
2090: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
20a0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
20b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
20c0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
20d0: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
20e0: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
20f0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2100: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2110: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2120: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2130: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2140: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2150: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
2160: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
2170: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
2180: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
2190: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
21a0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
21b0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
21c0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
21d0: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
21e0: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
21f0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2200: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2210: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2220: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2230: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2240: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2260: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2270: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2280: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
2290: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
22a0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
22b0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
22c0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
22d0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
22e0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
22f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2300: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2310: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2320: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2330: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2340: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2350: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2360: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2370: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2380: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
2390: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
23a0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
23b0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
23c0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
23d0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
23e0: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
23f0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2400: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2410: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2420: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2430: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2440: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2450: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
2460: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
2470: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
2480: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
2490: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
24a0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
24b0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
24c0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
24d0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
24e0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
24f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2500: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2510: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2530: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2540: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2550: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
2560: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
2570: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2580: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
2590: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
25a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
25b0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
25c0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
25d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25e0: 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
25f0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2600: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2610: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2620: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2630: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2640: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2650: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
2660: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2670: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
2680: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
2690: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
26a0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
26b0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
26c0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
26d0: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
26e0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
26f0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2700: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2710: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2720: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2730: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2740: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2750: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
2760: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
2770: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2780: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2790: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
27a0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
27b0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
27c0: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
27d0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
27e0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
27f0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2800: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2810: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2820: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2830: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2840: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2850: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
2860: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
2870: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
2880: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
2890: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
28a0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
28b0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
28c0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
28d0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
28e0: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
28f0: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2900: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2910: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2920: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2930: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2940: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2950: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2960: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2970: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2980: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2990: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
29a0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
29b0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
29c0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
29d0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
29e0: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
29f0: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2a00: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2a10: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2a20: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2a30: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2a40: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2a50: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2a60: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2a70: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2a80: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2a90: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2aa0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2ab0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2ac0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2ad0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2ae0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2af0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2b00: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2b10: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2b20: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2b30: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2b40: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2b50: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2b60: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2b70: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2b80: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2b90: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ba0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2bb0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2bc0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2be0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2bf0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2c00: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2c10: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2c20: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2c30: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2c40: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2c50: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2c60: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2c70: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2c80: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2c90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ca0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2cb0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2cc0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2cd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2ce0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2cf0: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2d00: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2d10: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2d20: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2d30: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2d40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d50: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2d60: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2d70: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d80: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2d90: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2da0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2db0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2dc0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2dd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2de0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2df0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2e00: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2e10: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2e20: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2e30: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2e40: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2e50: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2e60: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2e70: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2e80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e90: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2ea0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2eb0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2ec0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ed0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2ee0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2ef0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2f00: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2f10: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2f20: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2f30: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2f40: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2f50: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2f60: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2f70: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2f80: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2f90: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2fa0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2fb0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2fc0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2fd0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2fe0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2ff0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3000: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3010: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3020: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3030: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3040: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3050: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
3060: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
3070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3080: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
3090: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
30a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
30b0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
30c0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
30d0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
30e0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
30f0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3100: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3110: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3120: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3130: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3140: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3150: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3180: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3190: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
31a0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
31b0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
31c0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
31d0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
31e0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
31f0: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3200: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3210: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3220: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3230: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3240: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3250: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3260: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3280: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3290: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
32a0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
32b0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
32c0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
32d0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
32e0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
32f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3300: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3310: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3320: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3330: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3340: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3350: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3360: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3370: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3380: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3390: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
33b0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
33c0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
33d0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
33e0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
33f0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3400: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3410: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3420: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3430: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3440: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3450: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3460: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3470: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3480: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
3490: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
34a0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
34b0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
34c0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
34d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
34e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
34f0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3500: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3510: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3520: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3530: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3550: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3560: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3570: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
3580: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
3590: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
35a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
35b0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
35c0: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
35d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35e0: 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
35f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3600: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3610: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3620: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3630: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3640: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3650: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
3660: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
3670: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
3680: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
3690: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
36a0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
36b0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
36c0: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
36d0: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
36e0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
36f0: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3700: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3710: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3720: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3730: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3740: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3750: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
3760: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3770: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
3780: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
3790: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
37a0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
37b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
37c0: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
37d0: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
37e0: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
37f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3800: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3810: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3820: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3830: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3840: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3850: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
3860: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
3870: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3880: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
3890: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
38a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
38b0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
38c0: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
38d0: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
38e0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
38f0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3900: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3910: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3920: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3930: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3940: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3950: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3960: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3970: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3980: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3990: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
39a0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
39b0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
39c0: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
39d0: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
39e0: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
39f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3a00: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3a10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3a20: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3a30: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3a40: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3a50: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3a60: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3a70: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3a80: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3a90: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3aa0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3ab0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3ac0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3ad0: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3af0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3b00: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3b10: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3b20: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3b30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3b40: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3b50: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3b60: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3b70: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3b80: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3b90: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ba0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3bb0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3bc0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3bd0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3be0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3bf0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3c00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3c10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3c20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3c30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3c40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3c50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3c60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3c70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3c80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3c90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3ca0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3cb0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3cc0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3cd0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ce0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3cf0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3d20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3d50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3d60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3d70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3d80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3d90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3da0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3db0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3dc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3dd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3de0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3df0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3e00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3e10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3e20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3e30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3e40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3e50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3e60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3e70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3e80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3e90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ea0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3eb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3ec0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3ed0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ee0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3ef0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3f10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3f20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3f30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3f40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3f50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3f60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3f70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3f80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3f90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3fa0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3fb0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3fc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3fd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3fe0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3ff0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4000: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4010: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4020: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4030: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4040: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4050: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
4060: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4070: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
4080: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4090: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
40a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
40b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
40c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
40d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
40e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
40f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4100: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4110: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4120: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4130: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4140: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4150: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4160: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4170: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4180: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4190: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
41a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
41b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
41c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
41d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4200: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4210: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4240: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4250: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4260: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4270: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4280: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4290: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
42d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
42e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
42f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4310: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4320: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4330: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4340: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4350: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4360: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4370: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4380: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4390: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
43a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
43b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
43c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
43d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
43e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
43f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4400: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4410: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4420: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4430: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4440: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4450: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4460: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4470: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4480: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4490: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
44a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
44b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
44c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
44d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
44e0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
44f0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4510: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4520: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4530: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4540: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4550: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4560: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4570: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4580: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4590: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
45a0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
45b0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
45c0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
45d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45e0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
45f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4600: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4610: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4620: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4630: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4640: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4650: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4670: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4680: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4690: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
46b0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
46c0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
46d0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
46e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
46f0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4700: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4710: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4720: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4740: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4750: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4760: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4770: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4780: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4790: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
47a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
47b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
47c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
47d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
47e0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
47f0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4800: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4810: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4820: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4830: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4840: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4850: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4860: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4870: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4880: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4890: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
48a0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
48b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
48c0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
48d0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
48e0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
48f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4900: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4910: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4920: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4930: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4940: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4950: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4960: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4970: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4980: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4990: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
49a0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
49b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
49c0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
49d0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
49e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
49f0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4a00: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4a10: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4a20: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4a30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a40: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4a50: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4a60: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a80: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4a90: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4aa0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4ab0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4ad0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4ae0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4af0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4b00: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4b10: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4b20: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4b30: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4b50: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4b60: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4b70: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4b80: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4ba0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4bb0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4bc0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4bd0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4bf0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4c00: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4c10: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4c20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4c30: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4c40: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4c50: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4c60: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4c70: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4c80: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4c90: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4ca0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4cb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4cc0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4cd0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4ce0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4cf0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4d00: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4d10: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4d20: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4d30: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4d40: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4d50: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4d60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4d70: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4d80: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4d90: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4da0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4db0: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4dc0: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4dd0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4de0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4df0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4e00: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4e10: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4e20: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4e30: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4e40: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4e50: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4e60: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4e70: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e80: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e90: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4ea0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4eb0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4ec0: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74  rsion 3.3.8 [dat
4ed0: 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e  eof:3.3.8].** an
4ee0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4ef0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4f00: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4f10: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4f20: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4f30: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4f40: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4f50: 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20  These [extended 
4f60: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72  result codes] ar
4f70: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4f80: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f90: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4fa0: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4fb0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4fc0: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4fd0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20  t_codes()] API. 
4fe0: 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65   Or, the extende
4ff0: 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  d code for.** th
5000: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72  e most recent er
5010: 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69  ror can be obtai
5020: 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
5030: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
5040: 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64  rrcode()]..*/.#d
5050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5060: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
5070: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5080: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50a0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50c0: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
50d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50e0: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
50f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5100: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5110: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5120: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
5130: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5140: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5150: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5160: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
5170: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5180: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5190: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
51a0: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
51b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51c0: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
51d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
51e0: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
51f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5200: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
5210: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
5220: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5230: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5250: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
5260: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5270: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
52c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52d0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
52e0: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
52f0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
5300: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5310: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
5320: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5330: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
5340: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5350: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
5360: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5370: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
5380: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5390: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
53a0: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
53b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
53c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53d0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
53e0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
53f0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
5400: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5410: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
5420: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5430: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
5440: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5450: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
5460: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
5470: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
5480: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5490: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
54a0: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
54b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
54c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54d0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
54e0: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
54f0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
5500: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5510: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
5520: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
5530: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
5540: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5550: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
5560: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5570: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
5580: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5590: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
55a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
55b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
55c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55d0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
55e0: 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c  _NOENT      (SQL
55f0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c  ITE_IOERR | (23<
5600: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5610: 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20  ITE_IOERR_MMAP  
5620: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5630: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c  ITE_IOERR | (24<
5640: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5650: 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d  ITE_IOERR_GETTEM
5660: 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  PPATH       (SQL
5670: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c  ITE_IOERR | (25<
5680: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5690: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41  ITE_IOERR_CONVPA
56a0: 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TH          (SQL
56b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c  ITE_IOERR | (26<
56c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56d0: 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20  ITE_IOERR_VNODE 
56e0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
56f0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c  ITE_IOERR | (27<
5700: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5710: 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20  ITE_IOERR_AUTH  
5720: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5730: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c  ITE_IOERR | (28<
5740: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5750: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
5760: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
5770: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
5780: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5790: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
57a0: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
57b0: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
57c0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57d0: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53  QLITE_BUSY_SNAPS
57e0: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53  HOT           (S
57f0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
5800: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5810: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5820: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
5830: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5840: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5850: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5860: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
5870: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5880: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
5890: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
58a0: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
58b0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
58c0: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
58d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
58e0: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
58f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5900: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
5910: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5920: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5930: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5940: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5950: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5960: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5970: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5980: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5990: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
59a0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
59b0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
59c0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
59d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
59e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
59f0: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
5a00: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5a10: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5a20: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44  QLITE_READONLY_D
5a30: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53  BMOVED        (S
5a40: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5a50: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a60: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5a70: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5a80: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5a90: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5aa0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ab0: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5ac0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ad0: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5ae0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5af0: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5b00: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b10: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b30: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5b40: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5b50: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5b80: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5b90: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5ba0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bc0: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5bd0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5be0: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5bf0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c00: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5c10: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c20: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5c30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c40: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5c50: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c60: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5c70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c80: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5c90: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5ca0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5cb0: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5cc0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5cd0: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5ce0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5cf0: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5d00: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5d10: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5d20: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5d30: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d50: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5d60: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5d70: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d90: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5da0: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5db0: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5dd0: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5de0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5df0: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5e00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e10: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20  AUTH_USER       
5e20: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e30: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AUTH | (1<<8)).#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
5e50: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c  _LOAD_PERMANENTL
5e60: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b  Y     (SQLITE_OK
5e70: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5e80: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5e90: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5ea0: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5eb0: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5ec0: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5ed0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5ee0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5ef0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5f00: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5f10: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5f20: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5f30: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5f40: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5f50: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5f60: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5f70: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5f80: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5f90: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fa0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fb0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5fc0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5fd0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5fe0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5ff0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6000: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
6010: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6020: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
6030: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6040: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6050: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
6060: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
6070: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
6080: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6090: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
60a0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
60b0: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
60c0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60d0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
60e0: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
60f0: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
6100: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6110: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
6120: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6130: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
6140: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6150: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6160: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
6170: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6180: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
6190: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
61a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
61b0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
61c0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61d0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
61e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
61f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
6200: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6210: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
6220: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6230: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
6240: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
6250: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
6260: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6270: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6280: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6290: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
62a0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
62c0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
62d0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
62e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62f0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
6300: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
6310: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
6320: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6330: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
6340: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
6350: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
6360: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6370: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6380: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
6390: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
63a0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
63b0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
63c0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
63d0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
63e0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
63f0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6400: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6410: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
6420: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
6430: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
6440: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6450: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6460: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
6470: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6480: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
6490: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
64a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
64b0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
64c0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
64d0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
64e0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
64f0: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6500: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6510: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
6520: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6530: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
6540: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
6550: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6560: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
6570: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6580: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6590: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
65a0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
65b0: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
65c0: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
65d0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
65e0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
65f0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6600: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6610: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
6620: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6630: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
6640: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
6650: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6660: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
6670: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6680: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6690: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
66a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
66b0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
66c0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
66d0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
66e0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
66f0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6700: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6710: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
6720: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6730: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6740: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6750: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6760: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6770: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6780: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6790: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
67a0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
67b0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
67c0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
67d0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
67e0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
67f0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6800: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6810: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6820: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6830: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6840: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6850: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6860: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6870: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6880: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6890: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
68a0: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
68b0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
68c0: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
68d0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
68e0: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
68f0: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6900: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6910: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
6920: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6930: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6940: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6950: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6960: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6970: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6980: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6990: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
69a0: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
69b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
69c0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
69d0: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
69e0: 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c  cates that a fil
69f0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6a00: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
6a10: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
6a20: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6a30: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6a40: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6a50: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6a60: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6a70: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6a80: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6a90: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6aa0: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6ac0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6ad0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ae0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6af0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6b00: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6b10: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6b20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b30: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6b40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b60: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b80: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ba0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6bb0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6bc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6bd0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6be0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bf0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6c00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6c10: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6c20: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6c30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c40: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6c50: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c60: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6c70: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6c80: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6c90: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6ca0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6cb0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6cc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6cd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6ce0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6cf0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6d00: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6d10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6d20: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6d30: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d50: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6d60: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6d70: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6d80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6d90: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6da0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6db0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6dc0: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6dd0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6de0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6df0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6e00: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6e10: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6e20: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6e30: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6e40: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6e50: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6e60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6e70: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6e80: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6e90: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6ea0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6eb0: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6ec0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6ed0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6ee0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6ef0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6f00: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6f10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6f20: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6f30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6f40: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6f50: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6f60: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6f70: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6f80: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6f90: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6fa0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6fb0: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6fc0: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6fd0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6fe0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6ff0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
7000: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
7010: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
7020: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
7030: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
7040: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
7050: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
7060: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
7070: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
7080: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
7090: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
70a0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
70b0: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
70c0: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
70d0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
70e0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
70f0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
7100: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
7110: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
7120: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
7130: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
7140: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
7150: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7160: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7170: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7180: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7190: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
71a0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
71b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
71c0: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
71d0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
71e0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
71f0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
7200: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
7210: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
7220: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
7230: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7240: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
7250: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7260: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7270: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7280: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7290: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
72a0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
72b0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
72c0: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
72d0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
72e0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
72f0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
7300: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
7310: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
7320: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
7330: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7340: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
7350: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7360: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7370: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7380: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7390: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
73a0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
73b0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
73c0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
73d0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
73e0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
73f0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
7400: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
7410: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
7420: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
7430: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7440: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
7450: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7460: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7480: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7490: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
74a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
74b0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
74c0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
74d0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
74e0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
74f0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
7500: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7510: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
7520: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
7530: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7540: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
7550: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7560: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7570: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7580: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7590: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
75a0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
75b0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
75c0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
75d0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
75e0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
75f0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7600: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
7610: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7620: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7630: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7640: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
7650: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7660: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7670: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7680: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7690: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
76a0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
76b0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
76c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
76d0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
76e0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
76f0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7700: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7710: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
7720: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7730: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7740: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
7750: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7760: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7770: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7780: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7790: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
77a0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
77b0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
77c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
77d0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
77e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
77f0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7800: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
7810: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7820: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7830: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7840: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
7850: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7860: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7870: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7880: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7890: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
78a0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
78b0: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
78c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
78d0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
78e0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
78f0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7900: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
7910: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
7920: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7930: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7940: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7950: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7960: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7970: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7980: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7990: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
79a0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
79b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
79c0: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
79d0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
79e0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
79f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7a00: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
7a10: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
7a20: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7a30: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7a40: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
7a50: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7a60: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7a70: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7a80: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7a90: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7aa0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7ab0: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7ac0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7ad0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7ae0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7af0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7b00: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7b10: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7b20: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7b30: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7b40: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
7b50: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
7b60: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7b70: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7b80: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7b90: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7ba0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7bb0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7bc0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7bd0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7be0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7bf0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7c00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7c10: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7c20: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7c30: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7c40: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7c50: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7c60: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7c70: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7c80: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7c90: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7ca0: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7cb0: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7cc0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7cd0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7ce0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7cf0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7d00: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7d10: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7d20: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7d30: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7d40: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7d50: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7d60: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7d70: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7d80: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7d90: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7da0: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7db0: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7dc0: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7dd0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7de0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7df0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7e00: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7e10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7e20: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7e30: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7e40: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7e50: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7e60: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7e70: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7e80: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7e90: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7ea0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7eb0: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7ec0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7ed0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7ee0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7ef0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7f00: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7f10: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7f20: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7f30: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7f40: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7f50: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7f60: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7f70: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7f80: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7f90: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7fa0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7fb0: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7fc0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7fd0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7fe0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7ff0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
8000: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
8010: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
8020: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
8030: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
8040: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
8050: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
8060: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
8070: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
8080: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
8090: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
80a0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
80b0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
80c0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
80d0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
80e0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
80f0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
8100: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
8110: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
8120: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
8130: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8140: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8150: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8160: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8170: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8180: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8190: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
81a0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
81b0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
81c0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
81d0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
81e0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
81f0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8200: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
8210: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
8220: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8230: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8240: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8250: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8260: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8270: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8280: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8290: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
82a0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
82b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
82c0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
82d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
82e0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
82f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8300: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
8310: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8320: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8330: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8340: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8350: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8360: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8370: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8380: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8390: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
83a0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
83b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
83c0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
83d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
83e0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
83f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8400: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
8410: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8420: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
8430: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a  LE_WHEN_OPEN].**
8440: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8450: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
8460: 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e  ERWRITE].** <li>
8470: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
8480: 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75  MMUTABLE].** </u
8490: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
84a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
84b0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
84c0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
84d0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
84e0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
84f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8500: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
8510: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
8520: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
8530: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
8540: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
8550: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
8560: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
8570: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
8580: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
8590: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
85a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
85b0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
85c0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
85d0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
85e0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
85f0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
8600: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
8610: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
8620: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
8630: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
8640: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
8650: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8660: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
8670: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8680: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
8690: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
86a0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
86b0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
86c0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
86d0: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
86e0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
86f0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
8700: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
8710: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
8720: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
8730: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
8740: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
8750: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
8760: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8770: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
8780: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
8790: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
87a0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
87b0: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
87c0: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
87d0: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
87e0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
87f0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8800: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
8810: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
8820: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8830: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
8840: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
8850: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
8860: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8870: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
8880: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8890: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
88a0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
88b0: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
88c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88d0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
88e0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
88f0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8900: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
8910: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8920: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
8930: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
8940: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
8950: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8960: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
8970: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8980: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8990: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
89a0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
89b0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
89c0: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
89d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
89e0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
89f0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
8a00: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8a10: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
8a20: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
8a30: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8a40: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
8a50: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
8a60: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
8a70: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8a80: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8a90: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8aa0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8ab0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8ac0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ad0: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8ae0: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8af0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8b00: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8b10: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
8b20: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
8b30: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8b40: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
8b50: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
8b60: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
8b70: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8b80: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8b90: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8ba0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8bb0: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8bc0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8bd0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8be0: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8bf0: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8c00: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8c10: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8c20: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
8c30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
8c40: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8c50: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8c60: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
8c70: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8c80: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8c90: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8ca0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8cb0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8cc0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8cd0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8ce0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8cf0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8d00: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8d10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
8d20: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8d30: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
8d40: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
8d50: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8d60: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8d70: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8d80: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8d90: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8da0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8db0: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8dc0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8dd0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8de0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rface..**.** <ul
8df0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
8e00: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8e10: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8e20: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8e30: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8e40: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8e50: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8e60: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8e70: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8e80: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8e90: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8ea0: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8eb0: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8ec0: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8ed0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8ee0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8ef0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8f00: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8f10: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8f20: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8f30: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8f40: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8f50: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8f60: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8f70: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8f80: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73  g testing and is
8f90: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
8fa0: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  when the SQLITE_
8fb0: 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  TEST.** compile-
8fc0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75  time option is u
8fd0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  sed..**.** <li>[
8fe0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8ff0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
9000: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
9010: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
9020: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
9030: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
9040: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
9050: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
9060: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9070: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
9080: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
9090: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
90a0: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
90b0: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
90c0: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
90d0: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
90e0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
90f0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
9100: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
9110: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
9120: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
9130: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
9140: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
9150: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
9160: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9170: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
9180: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9190: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
91a0: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
91b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
91c0: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
91d0: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
91e0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
91f0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
9200: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
9210: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
9220: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
9230: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
9240: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
9250: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
9260: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9270: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
9280: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
9290: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
92a0: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
92b0: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
92c0: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
92d0: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
92e0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
92f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
9300: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
9310: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
9320: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
9330: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
9340: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
9350: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
9360: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
9370: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9380: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9390: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
93a0: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
93b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
93c0: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
93d0: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
93e0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
93f0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9400: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9410: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
9420: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9430: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9440: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9450: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9460: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9470: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9480: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
9490: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
94a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
94b0: 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  AL_POINTER] opco
94c0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
94d0: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
94e0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
94f0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9500: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
9510: 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  he journal file 
9520: 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b  (either.** the [
9530: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
9540: 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d  ] or the [write-
9550: 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20  ahead log]) for 
9560: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9570: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9580: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
9590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
95a0: 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  E_POINTER]..**.*
95b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
95c0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
95d0: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
95e0: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
95f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9600: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
9610: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9620: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9630: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9640: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
9650: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
9660: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
9670: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
9680: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
9690: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
96a0: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
96b0: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
96c0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
96d0: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
96e0: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
96f0: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
9700: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
9710: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
9720: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9730: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9740: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
9750: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
9760: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
9770: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
9780: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
9790: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
97a0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
97b0: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
97c0: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
97d0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
97e0: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
97f0: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
9800: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
9810: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
9820: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9830: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9840: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
9850: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
9860: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
9870: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
9880: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
9890: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
98a0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
98b0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
98c0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
98d0: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
98e0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
98f0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9900: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9910: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
9920: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9930: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9940: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9950: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9960: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9970: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9980: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
9990: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
99a0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
99b0: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
99c0: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
99d0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
99e0: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
99f0: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
9a00: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
9a10: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
9a20: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9a30: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9a40: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
9a50: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
9a60: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9a70: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
9a80: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9a90: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9aa0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
9ab0: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
9ac0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9ad0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
9ae0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9af0: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9b00: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9b10: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9b20: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9b30: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9b40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b50: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9b60: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
9b70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9b80: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b90: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9ba0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
9bb0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
9bc0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
9bd0: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
9be0: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
9bf0: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9c00: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9c10: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9c20: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9c30: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9c40: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
9c50: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
9c60: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9c70: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9c80: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9c90: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
9ca0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
9cb0: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
9cc0: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
9cd0: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
9ce0: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
9cf0: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9d00: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9d10: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9d20: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9d30: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9d40: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
9d50: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
9d60: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9d70: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9d80: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9d90: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9da0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9db0: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9dc0: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9dd0: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9de0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9df0: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9e00: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9e10: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9e20: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9e30: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9e40: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9e50: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9e60: 65 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20  eger is the new 
9e70: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
9e80: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
9e90: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
9ea0: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
9eb0: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
9ec0: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
9ed0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
9ee0: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
9ef0: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
9f00: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
9f10: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
9f20: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
9f30: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
9f40: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
9f50: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
9f60: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
9f70: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
9f80: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
9f90: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  red..**.** <li>[
9fa0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9fb0: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e  RSIST_WAL]].** ^
9fc0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9fd0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f  L_PERSIST_WAL] o
9fe0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9ff0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a000: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a010: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65  [WAL | Write Ahe
a020: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e  ad Log] setting.
a030: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
a040: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77  e auxiliary.** w
a050: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61  rite ahead log a
a060: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a070: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20   files used for 
a080: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
a090: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d  rol.** are autom
a0a0: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
a0b0: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74   when the latest
a0c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74   connection to t
a0d0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
a0e0: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20  loses.  Setting 
a0f0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
a100: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65  ode causes those
a110: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73   files to persis
a120: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65  t after.** close
a130: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68  .  Persisting th
a140: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75  e files is usefu
a150: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f  l when other pro
a160: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e  cesses that do n
a170: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65  ot.** have write
a180: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74   permission on t
a190: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e  he directory con
a1a0: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61  taining the data
a1b0: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a  base file want.*
a1c0: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  * to read the da
a1d0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20  tabase file, as 
a1e0: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72  the WAL and shar
a1f0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
a200: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e  must exist.** in
a210: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64   order for the d
a220: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
a230: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75  adable.  The fou
a240: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a250: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a260: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a270: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a280: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a290: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a2a0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a2b0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a2c0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
a2d0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a2e0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a  le persistent.**
a2f0: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74   WAL mode.  If t
a300: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a310: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a320: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a330: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c  e current.** WAL
a340: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74   persistence set
a350: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a360: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a370: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a380: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a390: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a3a0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a3b0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a3c0: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
a3d0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
a3e0: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
a3f0: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
a400: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
a410: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
a420: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
a430: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
a440: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a450: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
a460: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a470: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
a480: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a490: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a4a0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a4b0: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a4c0: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a4d0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a4e0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a4f0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a500: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
a510: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
a520: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
a530: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
a540: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a550: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a560: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a570: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
a580: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
a590: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a5a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a5b0: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
a5c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a5d0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
a5e0: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
a5f0: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
a600: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
a610: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
a620: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
a630: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
a640: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
a650: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
a660: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
a670: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
a680: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
a690: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
a6a0: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
a6b0: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
a6c0: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
a6d0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a6e0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a  FCNTL_VFSNAME]].
a6f0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a700: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
a710: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
a720: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
a730: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
a740: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
a750: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
a760: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
a770: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
a780: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
a790: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
a7a0: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
a7b0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
a7c0: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
a7d0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
a7e0: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
a7f0: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
a800: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
a810: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
a820: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
a830: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a840: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
a850: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
a860: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
a870: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
a880: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
a890: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
a8a0: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
a8b0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
a8c0: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
a8d0: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
a8e0: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
a8f0: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
a900: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
a910: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
a920: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
a930: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
a940: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
a950: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
a960: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
a970: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
a980: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
a990: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a   use only..**.**
a9a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a9b0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
a9c0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a9d0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
a9e0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64  TER] opcode find
a9f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
aa00: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20  he top-level.** 
aa10: 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c  [VFSes] currentl
aa20: 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65  y in use.  ^(The
aa30: 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a   argument X in.*
aa40: 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  * sqlite3_file_c
aa50: 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45  ontrol(db,SQLITE
aa60: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
aa70: 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a  ER,X) must be.**
aa80: 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74   of type "[sqlit
aa90: 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68  e3_vfs] **".  Th
aaa0: 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20  is opcodes will 
aab0: 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70  set *X.** to a p
aac0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
aad0: 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a  p-level VFS.)^.*
aae0: 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72  * ^When there ar
aaf0: 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73  e multiple VFS s
ab00: 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63  hims in the stac
ab10: 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66  k, this opcode f
ab20: 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65  inds the.** uppe
ab30: 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79  r-most shim only
ab40: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ab50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ab60: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
ab70: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
ab80: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
ab90: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
aba0: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
abb0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
abc0: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
abd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
abe0: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
abf0: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
ac00: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
ac10: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
ac20: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
ac30: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
ac40: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
ac50: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ac60: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
ac70: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
ac80: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
ac90: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
aca0: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
acb0: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
acc0: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
acd0: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
ace0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
acf0: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
ad00: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
ad10: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
ad20: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
ad30: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
ad40: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
ad50: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
ad60: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ad70: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
ad80: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
ad90: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
ada0: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
adb0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
adc0: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
add0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
ade0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
adf0: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
ae00: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
ae10: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
ae20: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
ae30: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
ae40: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
ae50: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
ae60: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
ae70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ae80: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ae90: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
aea0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
aeb0: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
aec0: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
aed0: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
aee0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
aef0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
af00: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
af10: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
af20: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
af30: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
af40: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
af50: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
af60: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
af70: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
af80: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
af90: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66  red statement if
afa0: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69   result string i
afb0: 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20  s NULL, or that 
afc0: 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a  returns a copy.*
afd0: 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
afe0: 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74  string if the st
aff0: 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c  ring is non-NULL
b000: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  ..** ^If the [SQ
b010: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b020: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b030: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
b040: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
b050: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
b060: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
b070: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
b080: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
b090: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
b0a0: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
b0b0: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
b0c0: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
b0d0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
b0e0: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
b0f0: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
b100: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b110: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b120: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
b130: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
b140: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
b150: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
b160: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
b170: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
b180: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
b190: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
b1a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b1b0: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b1c0: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
b1d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b1e0: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
b1f0: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
b200: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
b210: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
b220: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
b230: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
b240: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
b250: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
b260: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
b270: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
b280: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
b290: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
b2a0: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
b2b0: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
b2c0: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
b2d0: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
b2e0: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
b2f0: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
b300: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
b310: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
b320: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
b330: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
b340: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
b350: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
b360: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
b370: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
b380: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
b390: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
b3a0: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
b3b0: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
b3c0: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
b3d0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
b3e0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
b3f0: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
b400: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
b410: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
b420: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
b430: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
b440: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
b450: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
b460: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b470: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
b480: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
b490: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
b4a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b4b0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
b4c0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
b4d0: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
b4e0: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
b4f0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
b500: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
b510: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
b520: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
b530: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
b540: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
b550: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
b560: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
b570: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
b580: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
b590: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
b5a0: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
b5b0: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
b5c0: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
b5d0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
b5e0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
b5f0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
b600: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
b610: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
b620: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
b630: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
b640: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
b650: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b660: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b670: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b680: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b690: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b6a0: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
b6b0: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
b6c0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b6d0: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
b6e0: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
b6f0: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
b700: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b710: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b720: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
b730: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
b740: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
b750: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
b760: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
b770: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
b780: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
b790: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
b7a0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
b7b0: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
b7c0: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
b7d0: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
b7e0: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
b7f0: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
b800: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
b810: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
b820: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
b830: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
b840: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b850: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
b860: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
b870: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
b880: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
b890: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
b8a0: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
b8b0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b8c0: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
b8d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b8e0: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
b8f0: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
b900: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
b910: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
b920: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
b930: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
b940: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
b950: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
b960: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
b970: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
b980: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
b990: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
b9a0: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b9b0: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
b9c0: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
b9d0: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
b9e0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
b9f0: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
ba00: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
ba10: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
ba20: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
ba30: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
ba40: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
ba50: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
ba60: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ba70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
ba80: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  OVED]].** The [S
ba90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
baa0: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74  MOVED] file cont
bab0: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
bac0: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
bad0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
bae0: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74  n integer and it
baf0: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61   writes a boolea
bb00: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  n into that inte
bb10: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a  ger depending.**
bb20: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e   on whether or n
bb30: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20  ot the file has 
bb40: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f  been renamed, mo
bb50: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ved, or deleted 
bb60: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20  since it.** was 
bb70: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a  first opened..**
bb80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bb90: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
bba0: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
bbb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
bbc0: 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d  IN32_GET_HANDLE]
bbd0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
bbe0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
bbf0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
bc00: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
bc10: 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
bc20: 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65  th a file handle
bc30: 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20  .  This file.** 
bc40: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
bc50: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
bc60: 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  as a pointer to 
bc70: 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61  a native file ha
bc80: 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74  ndle and.** writ
bc90: 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  es the resulting
bca0: 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a   value there..**
bcb0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bcc0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
bcd0: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
bce0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
bcf0: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
bd00: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
bd10: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
bd20: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
bd30: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
bd40: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
bd50: 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68   swap the file h
bd60: 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f  andle with the o
bd70: 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ne.** pointed to
bd80: 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67   by the pArg arg
bd90: 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70  ument.  This cap
bda0: 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20  ability is used 
bdb0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a  during testing.*
bdc0: 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  * and only needs
bdd0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
bde0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
bdf0: 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  T is defined..**
be00: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
be10: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
be20: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
be30: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
be40: 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74  K] is a signal t
be50: 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20  o the VFS layer 
be60: 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a  that it might.**
be70: 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73   be advantageous
be80: 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65   to block on the
be90: 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69   next WAL lock i
bea0: 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f  f the lock is no
beb0: 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  t immediately.**
bec0: 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65   available.  The
bed0: 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69   WAL subsystem i
bee0: 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61  ssues this signa
bef0: 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a  l during rare.**
bf00: 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69   circumstances i
bf10: 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61  n order to fix a
bf20: 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72   problem with pr
bf30: 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e  iority inversion
bf40: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
bf50: 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74  s should <em>not
bf60: 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66  </em> use this f
bf70: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a  ile-control..**.
bf80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bf90: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a  FCNTL_ZIPVFS]].*
bfa0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bfb0: 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f  NTL_ZIPVFS] opco
bfc0: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
bfd0: 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79  d by zipvfs only
bfe0: 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56  . All other.** V
bff0: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
c000: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
c010: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
c020: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c030: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d  LITE_FCNTL_RBU]]
c040: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c050: 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64  FCNTL_RBU] opcod
c060: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c070: 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20   by the special 
c080: 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74  VFS used by.** t
c090: 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e  he RBU extension
c0a0: 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65   only.  All othe
c0b0: 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  r VFS should ret
c0c0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c0d0: 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20  UND for.** this 
c0e0: 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75  opcode.  .** </u
c0f0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
c100: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
c110: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
c120: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
c130: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
c140: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c150: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
c160: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
c170: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
c180: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
c190: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
c1a0: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
c1b0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c1c0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
c1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
c1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1f0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
c200: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
c210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c220: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
c230: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
c240: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c250: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
c260: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
c270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c280: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
c290: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
c2a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c2b0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
c2c0: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
c2d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2e0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
c2f0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
c300: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c310: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
c320: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
c330: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
c340: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c350: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
c360: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
c370: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
c380: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
c390: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
c3a0: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
c3b0: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
c3c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
c3d0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
c3e0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
c3f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
c400: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
c410: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
c420: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
c430: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c440: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
c450: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
c460: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
c470: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
c480: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
c490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
c4a0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
c4b0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
c4c0: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
c4d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c4e0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
c4f0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
c500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c510: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20  CNTL_WAL_BLOCK  
c520: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23              24.#
c530: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c540: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20  NTL_ZIPVFS      
c550: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64             25.#d
c560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c570: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20  TL_RBU          
c580: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65            26.#de
c590: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c5a0: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20  L_VFS_POINTER   
c5b0: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66           27.#def
c5c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c5d0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
c5e0: 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69          28.#defi
c5f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c600: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
c610: 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e         29.#defin
c620: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
c630: 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20  DB              
c640: 20 20 20 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70        30../* dep
c650: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
c660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c670: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c680: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c690: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
c6a0: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c6b0: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
c6c0: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c6d0: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
c6e0: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c6f0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
c700: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
c710: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c720: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
c730: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
c740: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
c750: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
c760: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
c770: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
c780: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
c790: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
c7a0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
c7b0: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
c7c0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
c7d0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
c7e0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
c7f0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
c800: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
c810: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
c820: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
c830: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c840: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
c850: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
c860: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c870: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
c880: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c890: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
c8a0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
c8b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c8c0: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73   Loadable Extens
c8d0: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20  ion Thunk.**.** 
c8e0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
c8f0: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f   opaque sqlite3_
c900: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72  api_routines str
c910: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64  ucture is passed
c920: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64   as.** the third
c930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e   parameter to en
c940: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c  try points of [l
c950: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
c960: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74  ns].  This.** st
c970: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20  ructure must be 
c980: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64  typedefed in ord
c990: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  er to work aroun
c9a0: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69  d compiler warni
c9b0: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70  ngs.** on some p
c9c0: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70  latforms..*/.typ
c9d0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
c9e0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
c9f0: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
ca00: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tines;../*.** CA
ca10: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
ca20: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
ca30: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
ca40: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
ca50: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
ca60: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
ca70: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
ca80: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
ca90: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
caa0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
cab0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
cac0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
cad0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
cae0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
caf0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
cb00: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
cb10: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
cb20: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
cb30: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
cb40: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
cb50: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
cb60: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
cb70: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
cb80: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
cb90: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
cba0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
cbb0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
cbc0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
cbd0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
cbe0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
cbf0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
cc00: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
cc10: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
cc20: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
cc30: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
cc40: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
cc50: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
cc60: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
cc70: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
cc80: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
cc90: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
cca0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
ccb0: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
ccc0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
ccd0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
cce0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
ccf0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
cd00: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
cd10: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
cd20: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
cd30: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
cd40: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
cd50: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
cd60: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
cd70: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
cd80: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
cd90: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
cda0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
cdb0: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
cdc0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
cdd0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
cde0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
cdf0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
ce00: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
ce10: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
ce20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
ce30: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
ce40: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
ce50: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
ce60: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ce70: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
ce80: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
ce90: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
cea0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
ceb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
cec0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
ced0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
cee0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
cef0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
cf00: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
cf10: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
cf20: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
cf30: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
cf40: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
cf50: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
cf60: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
cf70: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
cf80: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
cf90: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
cfa0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
cfb0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
cfc0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
cfd0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
cfe0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
cff0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
d000: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
d010: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
d020: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
d030: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
d040: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
d050: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
d060: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
d070: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
d080: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
d090: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d0a0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
d0b0: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
d0c0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
d0d0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
d0e0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
d0f0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
d100: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
d110: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
d120: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
d130: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d140: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
d150: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
d160: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
d170: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
d180: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
d190: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
d1a0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
d1b0: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
d1c0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
d1d0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
d1e0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
d1f0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
d200: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
d210: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
d220: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
d230: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
d240: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
d250: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
d260: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
d270: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
d280: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
d290: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
d2a0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
d2b0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
d2c0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
d2d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
d2e0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
d2f0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
d300: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
d310: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
d320: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
d330: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
d340: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
d350: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
d360: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
d370: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
d380: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
d390: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
d3a0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
d3b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d3c0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
d3d0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
d3e0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
d3f0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
d400: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
d410: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
d420: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
d430: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
d440: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
d450: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
d460: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
d470: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
d480: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
d490: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
d4a0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
d4b0: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
d4c0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
d4d0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
d4e0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
d4f0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
d500: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
d510: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
d520: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
d530: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
d540: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
d550: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
d560: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
d570: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
d580: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
d590: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
d5a0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
d5b0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
d5c0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
d5d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
d5e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d5f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
d600: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d610: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
d620: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
d630: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
d640: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
d650: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
d660: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
d670: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d680: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
d690: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d6a0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
d6b0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d6c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
d6d0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
d6e0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
d6f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
d700: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
d710: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
d720: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
d730: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
d740: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
d750: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
d760: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
d770: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
d780: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
d790: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
d7a0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
d7b0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
d7c0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
d7d0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
d7e0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
d7f0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
d800: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
d810: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
d820: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
d830: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
d840: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
d850: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
d860: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
d870: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
d880: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
d890: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
d8a0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
d8b0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
d8c0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
d8d0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
d8e0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
d8f0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
d900: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
d910: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d920: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d930: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d940: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d950: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d960: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d970: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d980: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d990: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d9a0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d9b0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d9c0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d9d0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d9e0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d9f0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
da00: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
da10: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
da20: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
da30: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
da40: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
da50: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
da60: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
da70: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
da80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
da90: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
daa0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
dab0: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
dac0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
dad0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
dae0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
daf0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
db00: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
db10: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
db20: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
db30: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
db40: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
db50: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
db60: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
db70: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
db80: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
db90: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
dba0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
dbb0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
dbc0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
dbd0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
dbe0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
dbf0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
dc00: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
dc10: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
dc20: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
dc30: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
dc40: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
dc50: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
dc60: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
dc70: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
dc80: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
dc90: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
dca0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
dcb0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
dcc0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
dcd0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
dce0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
dcf0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
dd00: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
dd10: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
dd20: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
dd30: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
dd40: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
dd50: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
dd60: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
dd70: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
dd80: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
dd90: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
dda0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
ddb0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
ddc0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
ddd0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
dde0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
ddf0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
de00: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
de10: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
de20: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
de30: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
de40: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
de50: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
de60: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
de70: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
de80: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
de90: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
dea0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
deb0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
dec0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
ded0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
dee0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
def0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
df00: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
df10: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
df20: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
df30: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
df40: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
df50: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
df60: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
df70: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
df80: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
df90: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
dfa0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
dfb0: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
dfc0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
dfd0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
dfe0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
dff0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
e000: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
e010: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
e020: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
e030: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
e040: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
e050: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
e060: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
e070: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
e080: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
e090: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
e0a0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
e0b0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
e0c0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
e0d0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
e0e0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
e0f0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
e100: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
e110: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
e120: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
e130: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
e140: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
e150: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
e160: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
e170: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
e180: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
e190: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
e1a0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
e1b0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
e1c0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
e1d0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
e1e0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
e1f0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
e200: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
e210: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
e220: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
e230: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
e240: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
e250: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
e260: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
e270: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
e280: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
e290: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
e2a0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
e2b0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
e2c0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
e2d0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
e2e0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
e2f0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
e300: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
e310: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
e320: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
e330: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
e340: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
e350: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
e360: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
e370: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
e380: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
e390: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
e3a0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
e3b0: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
e3c0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
e3d0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
e3e0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
e3f0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
e400: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
e410: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
e420: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
e430: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
e440: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
e450: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
e460: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
e470: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
e480: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
e490: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
e4a0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
e4b0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
e4c0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
e4d0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
e4e0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
e4f0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
e500: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
e510: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
e520: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
e530: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
e540: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
e550: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
e560: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
e570: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
e580: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
e590: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
e5a0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
e5b0: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
e5c0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
e5d0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
e5e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
e5f0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
e600: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
e610: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
e620: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
e630: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
e640: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
e650: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
e660: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
e670: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
e680: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
e690: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
e6a0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
e6b0: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
e6c0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
e6d0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
e6e0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
e6f0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
e700: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
e710: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
e720: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
e730: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
e740: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
e750: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
e760: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
e770: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
e780: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
e790: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e7a0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
e7b0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
e7c0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
e7d0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
e7e0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
e7f0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
e800: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
e810: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
e820: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
e830: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
e840: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
e850: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
e860: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
e870: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
e880: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
e890: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
e8a0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
e8b0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
e8c0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
e8d0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
e8e0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
e8f0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
e900: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e910: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e920: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e930: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e940: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e950: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e960: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e970: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e980: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e990: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e9a0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e9b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e9c0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e9d0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e9e0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e9f0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
ea00: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
ea10: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
ea20: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
ea30: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
ea40: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
ea50: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
ea60: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
ea70: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
ea80: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
ea90: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
eaa0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
eab0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
eac0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
ead0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
eae0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
eaf0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
eb00: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
eb10: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
eb20: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
eb30: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
eb40: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
eb50: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
eb60: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
eb70: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
eb80: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
eb90: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
eba0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
ebb0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ebc0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
ebd0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
ebe0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
ebf0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ec00: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
ec10: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
ec20: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
ec30: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
ec40: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
ec50: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
ec60: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
ec70: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
ec80: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
ec90: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
eca0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
ecb0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
ecc0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
ecd0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
ece0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
ecf0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
ed00: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
ed10: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
ed20: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
ed30: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
ed40: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
ed50: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
ed60: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
ed70: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ed80: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
ed90: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
eda0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
edb0: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
edc0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
edd0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
ede0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
edf0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
ee00: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
ee10: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
ee20: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
ee30: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
ee40: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
ee50: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
ee60: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ee70: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
ee80: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
ee90: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
eea0: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
eeb0: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
eec0: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
eed0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
eee0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
eef0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ef00: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ef10: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
ef20: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
ef30: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
ef40: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
ef50: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ef60: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ef70: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
ef80: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
ef90: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
efa0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
efb0: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
efc0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
efd0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
efe0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
eff0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
f000: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
f010: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
f020: 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72  ppended in futur
f030: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
f040: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
f050: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
f060: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
f070: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
f080: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
f090: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
f0a0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
f0b0: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
f0c0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
f0d0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
f0e0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
f0f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
f100: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
f110: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
f120: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
f130: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
f140: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
f150: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
f160: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
f170: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
f180: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f190: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
f1a0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
f1b0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
f1c0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
f1d0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
f1e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f1f0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
f200: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
f210: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f220: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
f230: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
f240: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
f250: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
f260: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
f270: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
f280: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
f290: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
f2a0: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
f2b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f2c0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
f2d0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
f2e0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
f2f0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
f300: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
f310: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
f320: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
f330: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
f340: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
f350: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f360: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
f370: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
f380: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f390: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
f3a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
f3b0: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
f3c0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
f3d0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
f3e0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
f3f0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
f400: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
f410: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
f420: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
f430: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
f440: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f450: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
f460: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
f470: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
f480: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
f490: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f4a0: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
f4b0: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
f4c0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
f4d0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
f4e0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
f4f0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
f500: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
f510: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
f520: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
f530: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
f540: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
f550: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
f560: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
f570: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
f580: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
f590: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
f5a0: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
f5b0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
f5c0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
f5d0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
f5e0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
f5f0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
f600: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
f610: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
f620: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
f630: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
f640: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f650: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
f660: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f670: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f680: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
f690: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
f6a0: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
f6b0: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
f6c0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
f6d0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
f6e0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
f6f0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
f700: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
f710: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f720: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
f730: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
f740: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
f750: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
f760: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
f770: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
f780: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
f790: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
f7a0: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
f7b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f7c0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
f7d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f7e0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
f7f0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
f800: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
f810: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
f820: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f830: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
f840: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
f850: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
f860: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f870: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
f880: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f890: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
f8a0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
f8b0: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
f8c0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
f8d0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
f8e0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
f8f0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
f900: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
f910: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f920: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f930: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f940: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f950: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f960: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f970: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f980: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f990: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f9a0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f9b0: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f9c0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f9d0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f9e0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f9f0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
fa00: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
fa10: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
fa20: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
fa30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fa40: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
fa50: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
fa60: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
fa70: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
fa80: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
fa90: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
faa0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
fab0: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
fac0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
fad0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
fae0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
faf0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
fb00: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
fb10: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
fb20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fb30: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
fb40: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
fb50: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
fb60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb70: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
fb80: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
fb90: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
fba0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
fbb0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
fbc0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
fbd0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
fbe0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
fbf0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
fc00: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
fc10: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
fc20: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
fc30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fc40: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
fc50: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
fc60: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
fc70: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
fc80: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
fc90: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fca0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
fcb0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
fcc0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
fcd0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
fce0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fcf0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
fd00: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fd10: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
fd20: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
fd30: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fd40: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
fd50: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
fd60: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
fd70: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
fd80: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fd90: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
fda0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
fdb0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
fdc0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
fdd0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
fde0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
fdf0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
fe00: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
fe10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
fe20: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
fe30: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
fe40: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
fe50: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
fe60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fe70: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
fe80: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
fe90: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
fea0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
feb0: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
fec0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
fed0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fee0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
fef0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
ff00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ff10: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
ff20: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
ff30: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
ff40: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
ff50: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
ff60: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
ff70: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
ff80: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ff90: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
ffa0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
ffb0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
ffc0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
ffd0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
ffe0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
fff0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
10000 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
10010 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
10020 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
10030 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
10040 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
10050 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
10060 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
10070 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
10080 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
10090 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
100a0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
100b0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
100c0 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
100d0 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
100e0 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
100f0 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
10100 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
10110 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
10120 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
10130 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
10140 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
10150 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
10160 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
10170 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10180 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
10190 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
101a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
101b0 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
101c0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
101d0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
101e0 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
101f0 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
10200 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
10210 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
10220 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
10230 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
10240 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
10250 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
10260 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
10270 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
10280 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10290 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
102a0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
102b0 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
102c0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
102d0 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
102e0 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
102f0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
10300 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
10310 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
10320 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
10330 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
10340 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
10350 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
10360 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
10370 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
10380 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
10390 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
103a0 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
103b0 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
103c0 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
103d0 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
103e0 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
103f0 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
10400 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
10410 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
10420 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
10430 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
10440 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
10450 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
10460 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
10470 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
10480 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
10490 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
104a0 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
104b0 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
104c0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
104d0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
104e0 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
104f0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
10500 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
10510 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
10520 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
10530 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
10540 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
10550 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
10560 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
10570 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
10580 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
10590 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
105a0 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
105b0 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
105c0 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
105d0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
105e0 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
105f0 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
10600 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
10610 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
10620 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
10630 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
10640 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
10650 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
10660 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10670 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
10680 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
10690 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
106a0 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
106b0 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
106c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
106d0 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
106e0 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
106f0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
10700 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
10710 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
10720 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
10730 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
10740 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10750 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
10760 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10770 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
10780 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10790 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
107a0 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
107b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
107c0 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
107d0 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
107e0 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
107f0 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
10800 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
10810 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
10820 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
10830 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
10840 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
10850 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
10860 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
10870 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
10880 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
10890 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
108a0 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
108b0 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
108c0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
108d0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
108e0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
108f0 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
10900 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
10910 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
10920 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10930 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
10940 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10950 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
10960 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10970 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10980 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10990 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
109a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
109b0 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
109c0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
109d0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
109e0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
109f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10a00 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
10a10 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10a20 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10a30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10a40 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10a50 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
10a60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10a70 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10a80 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
10a90 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
10aa0 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
10ab0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
10ac0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
10ad0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
10ae0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
10af0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
10b00 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
10b10 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
10b20 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10b30 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
10b40 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
10b50 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
10b60 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10b70 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10b80 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
10b90 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
10ba0 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
10bb0 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
10bc0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
10bd0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
10be0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
10bf0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
10c00 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
10c10 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
10c20 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10c30 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
10c40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10c50 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10c60 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
10c70 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
10c80 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
10c90 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
10ca0 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
10cb0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
10cc0 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
10cd0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10ce0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
10cf0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
10d00 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
10d10 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10d20 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
10d30 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10d40 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
10d50 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
10d60 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
10d70 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
10d80 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
10d90 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
10da0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
10db0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
10dc0 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
10dd0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
10de0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
10df0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
10e00 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10e10 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10e20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
10e30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10e40 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
10e50 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
10e60 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
10e70 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
10e80 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
10e90 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
10ea0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
10eb0 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
10ec0 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
10ed0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10ee0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
10ef0 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
10f00 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
10f10 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10f20 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10f30 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
10f40 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
10f50 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
10f60 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
10f70 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
10f80 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
10f90 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
10fa0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
10fb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
10fc0 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
10fd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10fe0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
10ff0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
11000 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
11010 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
11020 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11030 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
11040 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
11050 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
11060 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
11070 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
11080 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
11090 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
110a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
110b0 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
110c0 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
110d0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
110e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
110f0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
11100 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
11110 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
11120 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11130 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
11140 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
11150 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
11160 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11170 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
11180 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
11190 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
111a0 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
111b0 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
111c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
111d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
111e0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
111f0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
11200 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
11210 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
11220 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
11230 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
11240 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
11250 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
11260 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
11270 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
11280 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
11290 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
112a0 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
112b0 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
112c0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
112d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
112e0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
112f0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
11300 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11310 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
11320 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
11330 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
11340 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
11350 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11360 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
11370 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
11380 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
11390 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
113a0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
113b0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
113c0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
113d0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
113e0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
113f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11400 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
11410 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11420 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
11430 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
11440 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
11450 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
11460 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
11470 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11480 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
11490 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
114a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
114b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
114c0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
114d0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
114e0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
114f0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
11500 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
11510 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11520 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
11530 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
11540 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
11550 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
11560 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
11570 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
11580 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
11590 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
115a0 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
115b0 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
115c0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
115d0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
115e0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
115f0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
11600 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
11610 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
11620 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
11630 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
11640 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
11650 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
11660 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
11670 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
11680 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
11690 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
116a0 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
116b0 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
116c0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
116d0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
116e0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
116f0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
11700 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
11710 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
11720 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
11730 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
11740 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
11750 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
11760 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
11770 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
11780 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
11790 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
117a0 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
117b0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
117c0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
117d0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
117e0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
117f0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
11800 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
11810 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
11820 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
11830 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
11840 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
11850 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
11860 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
11870 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
11880 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11890 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
118a0 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
118b0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
118c0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
118d0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
118e0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
118f0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
11900 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
11910 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
11920 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
11930 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
11940 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
11950 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
11960 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11970 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
11980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
11990 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
119a0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
119b0 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
119c0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
119d0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
119e0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
119f0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
11a00 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
11a10 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
11a20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
11a30 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
11a40 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
11a50 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
11a60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11a70 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
11a80 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
11a90 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
11aa0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
11ab0 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
11ac0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
11ad0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
11ae0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
11af0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
11b00 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
11b10 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
11b20 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
11b30 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
11b40 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
11b50 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
11b60 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
11b70 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
11b80 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
11b90 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
11ba0 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
11bb0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
11bc0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11bd0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
11be0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
11bf0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11c00 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
11c10 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
11c20 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
11c30 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
11c40 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
11c50 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
11c60 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
11c70 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
11c80 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
11c90 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
11ca0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
11cb0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
11cc0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
11cd0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
11ce0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
11cf0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
11d00 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
11d10 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
11d20 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11d30 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
11d40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
11d50 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
11d60 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
11d70 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
11d80 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
11d90 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
11da0 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
11db0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
11dc0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
11dd0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
11de0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
11df0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11e00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11e10 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
11e20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
11e30 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
11e40 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
11e50 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11e60 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11e70 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11e80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11e90 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11ea0 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11eb0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11ec0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11ed0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
11ee0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11ef0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11f00 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
11f10 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
11f20 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11f30 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
11f40 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
11f50 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11f60 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11f70 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11f80 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11f90 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11fa0 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
11fb0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11fc0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
11fd0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
11fe0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11ff0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12000 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
12010 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
12020 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
12030 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
12040 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
12050 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
12060 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
12070 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
12080 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12090 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
120a0 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
120b0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
120c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
120d0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
120e0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
120f0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
12100 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
12110 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
12120 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
12130 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
12140 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
12150 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12160 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
12170 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
12180 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
12190 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
121a0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
121b0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
121c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
121d0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
121e0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
121f0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
12200 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
12210 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
12220 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
12230 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
12240 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
12250 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
12260 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
12270 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
12280 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
12290 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
122a0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
122b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
122c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
122d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
122e0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
122f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
12300 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
12310 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
12320 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
12330 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
12340 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
12350 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
12360 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
12370 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
12380 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
12390 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
123a0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
123b0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
123c0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
123d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
123e0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
123f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
12400 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
12410 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
12420 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
12430 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
12440 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
12450 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
12460 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
12470 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12480 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
12490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
124a0 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
124b0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
124c0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
124d0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
124e0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
124f0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12500 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
12510 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
12520 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
12530 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
12540 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
12550 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
12560 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
12570 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
12580 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
12590 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
125a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
125b0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
125c0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
125d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
125e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
125f0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12600 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12610 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
12620 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12630 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
12640 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
12650 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
12660 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12670 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12680 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
12690 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
126a0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
126b0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
126c0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
126d0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
126e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
126f0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
12700 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12710 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
12720 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12730 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12740 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12750 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12760 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12770 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12780 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
12790 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
127a0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
127b0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
127c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
127d0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
127e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
127f0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
12800 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
12810 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
12820 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
12830 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12840 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12860 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
12870 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
12880 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
12890 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
128a0 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
128b0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
128c0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
128d0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
128e0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
128f0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
12900 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
12910 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
12920 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
12930 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12940 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12950 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12960 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12970 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12980 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12990 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
129a0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
129b0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
129c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
129d0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
129e0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
129f0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12a00 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
12a10 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
12a20 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12a30 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
12a40 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12a50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12a60 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12a70 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12a80 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12a90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
12aa0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
12ab0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12ac0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
12ad0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
12ae0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12af0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
12b00 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
12b10 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
12b20 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
12b30 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
12b40 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
12b50 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
12b60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12b70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12b80 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
12b90 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
12ba0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
12bb0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
12bc0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12bd0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
12be0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
12bf0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12c00 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
12c10 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
12c20 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
12c30 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12c40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12c50 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
12c60 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
12c70 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
12c80 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
12c90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
12ca0 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
12cb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12cc0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
12cd0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
12ce0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
12cf0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12d00 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12d10 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12d20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12d30 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12d40 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12d50 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12d60 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12d70 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
12d80 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
12d90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12da0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
12db0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12dc0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
12dd0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
12de0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12df0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12e00 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12e10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12e20 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
12e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12e40 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12e50 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12e60 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12e70 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12e80 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12e90 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
12ea0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12eb0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12ec0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12ed0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
12ee0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12ef0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12f00 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
12f10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12f20 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12f30 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12f40 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12f50 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12f60 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12f70 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12f80 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12f90 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12fa0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12fb0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12fc0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12fd0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
12fe0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12ff0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
13000 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13010 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13020 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
13030 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13040 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
13050 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13060 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
13070 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13080 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13090 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
130a0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
130b0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
130c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
130d0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
130e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
130f0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
13100 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
13110 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
13120 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
13130 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13140 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
13150 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
13160 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
13170 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
13180 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13190 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
131a0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
131b0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
131c0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
131d0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
131e0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
131f0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
13200 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13210 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
13220 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13230 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
13240 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13260 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
13270 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
13280 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
13290 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
132a0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
132b0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
132c0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
132d0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
132e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
132f0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
13300 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
13310 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
13320 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
13330 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
13340 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13350 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
13360 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
13370 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
13380 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
13390 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
133a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
133b0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
133c0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
133d0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
133e0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
133f0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
13400 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
13410 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
13420 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13430 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
13440 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
13450 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
13460 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
13470 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
13480 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
13490 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
134a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
134b0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
134c0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
134d0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
134e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
134f0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
13500 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13510 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13520 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13530 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
13540 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13550 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13560 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13570 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
13580 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
13590 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
135a0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
135b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
135c0 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
135d0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
135e0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
135f0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
13600 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
13610 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
13620 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
13630 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
13640 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
13650 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
13660 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
13670 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13680 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
13690 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
136a0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
136b0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
136c0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
136d0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
136e0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
136f0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
13700 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
13710 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
13720 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
13730 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
13740 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
13750 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
13760 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
13770 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
13780 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
13790 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
137a0 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
137b0 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
137c0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
137d0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
137e0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
137f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13800 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
13810 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13820 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
13830 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
13840 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
13850 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
13860 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
13870 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
13880 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
13890 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
138a0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
138b0 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
138c0 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
138d0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
138e0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
138f0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
13900 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
13910 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
13920 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13930 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
13940 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
13950 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
13960 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
13970 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
13980 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13990 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
139a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
139b0 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
139c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
139d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
139e0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
139f0 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20  cifies a memory 
13a00 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c  pool.** that SQL
13a10 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
13a20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
13a30 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
13a40 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a   default page.**
13a50 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13a60 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
13a70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13a80 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70  ption is a no-op
13a90 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
13aa0 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
13ab0 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
13ac0 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
13ad0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
13ae0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13af0 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  2]..** ^There ar
13b00 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13b10 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
13b20 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
13b30 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
13b40 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d  byte aligned mem
13b50 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20  ory (pMem), the 
13b60 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
13b70 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a  e cache line (sz
13b80 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75  ),.** and the nu
13b90 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69  mber of cache li
13ba0 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  nes (N)..** The 
13bb0 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
13bc0 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
13bd0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
13be0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
13bf0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
13c00 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36  etween 512 and 6
13c10 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20  5536) plus some 
13c20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20  extra bytes for 
13c30 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
13c40 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65  der.  ^The numbe
13c50 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73  r of extra bytes
13c60 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70   needed by the p
13c70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61  age header.** ca
13c80 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
13c90 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f  using [SQLITE_CO
13ca0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
13cb0 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  Z]..** ^It is ha
13cc0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
13cd0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
13ce0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
13cf0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
13d00 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
13d10 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
13d20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  pMem.** argument
13d30 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
13d40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
13d50 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  r a pointer to a
13d60 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
13d70 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  ned block of mem
13d80 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
13d90 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65  sz*N bytes, othe
13da0 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75  rwise.** subsequ
13db0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ent behavior is 
13dc0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57  undefined..** ^W
13dd0 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20  hen pMem is not 
13de0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
13df0 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20  l strive to use 
13e00 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
13e10 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66  ded.** to satisf
13e20 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65  y page cache nee
13e30 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b  ds, falling back
13e40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13e50 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70  loc()] if.** a p
13e60 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69  age cache line i
13e70 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a  s larger than sz
13e80 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c   bytes or if all
13e90 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66   of the pMem buf
13ea0 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73  fer.** is exhaus
13eb0 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d  ted..** ^If pMem
13ec0 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69   is NULL and N i
13ed0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
13ee0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
13ef0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65  onnection.** doe
13f00 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c  s an initial bul
13f10 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  k allocation for
13f20 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13f30 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ry.** from [sqli
13f40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75  te3_malloc()] su
13f50 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63  fficient for N c
13f60 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20  ache lines if N 
13f70 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a  is positive or.*
13f80 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74  * of -1024*N byt
13f90 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  es if N is negat
13fa0 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74  ive, . ^If addit
13fb0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
13fc0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
13fd0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
13fe0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
13ff0 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61  the initial.** a
14000 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
14010 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
14020 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14030 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72  ] separately for
14040 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f   each.** additio
14050 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20  nal cache line. 
14060 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14080 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14090 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
140a0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
140b0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
140c0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
140d0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
140e0 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20  buffer .** that 
140f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
14100 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
14110 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
14120 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a  location needs.*
14130 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  * beyond those p
14140 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b  rovided for by [
14150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14160 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53  RATCH] and.** [S
14170 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
14180 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65  ECACHE]..** ^The
14190 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
141a0 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  EAP option is on
141b0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
141c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
141d0 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65  ed.** with eithe
141e0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
141f0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51  _MEMSYS3] or [SQ
14200 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
14210 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73  YS5] and returns
14220 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
14230 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74  R] if invoked ot
14240 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65  herwise..** ^The
14250 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
14260 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
14270 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a  _CONFIG_HEAP:.**
14280 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
14290 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
142a0 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
142b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
142c0 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
142d0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
142e0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
142f0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
14300 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
14310 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
14320 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
14330 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
14340 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
14350 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
14360 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
14370 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
14380 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
14390 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
143a0 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
143b0 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
143c0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
143d0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
143e0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
143f0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ULL then the alt
14400 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
14410 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
14420 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
14430 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
14440 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14450 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
14460 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
14470 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
14480 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
14490 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
144a0 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
144b0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
144c0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
144d0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
144e0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
144f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
14500 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
14510 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
14520 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
14530 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14540 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
14550 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
14560 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14570 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14580 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14590 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
145a0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
145b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
145c0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
145d0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
145e0 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70   which is a.** p
145f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
14600 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
14610 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14620 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14630 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
14640 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e  specifies altern
14650 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
14660 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
14670 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20  o be used.** in 
14680 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20  place the mutex 
14690 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
146a0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
146b0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
146c0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
146d0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
146e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
146f0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
14700 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
14710 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
14720 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
14730 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14740 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14750 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14760 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14770 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14780 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14790 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
147a0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
147b0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
147c0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
147d0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
147e0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
147f0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
14800 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
14810 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
14820 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14830 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14840 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14850 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14860 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
14870 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14880 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
14890 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
148a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
148b0 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  TMUTEX option ta
148c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
148d0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
148e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
148f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14900 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
14910 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14920 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
14930 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14940 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
14950 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
14960 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
14970 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
14980 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
14990 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
149a0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
149b0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
149c0 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
149d0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
149e0 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
149f0 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
14a00 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
14a10 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
14a20 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
14a30 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
14a40 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14a50 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
14a60 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
14a70 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
14a80 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14a90 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14aa0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
14ab0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
14ac0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
14ad0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
14ae0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
14af0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14b00 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
14b10 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14b20 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
14b30 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
14b40 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14b50 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
14b60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14b70 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
14b80 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14b90 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
14ba0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14bc0 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b  ASIDE option tak
14bd0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14be0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a   that determine.
14bf0 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ** the default s
14c00 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ize of lookaside
14c10 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20   memory on each 
14c20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14c30 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
14c40 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
14c50 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
14c60 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
14c70 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
14c80 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
14c90 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
14ca0 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
14cb0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
14cc0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53  nnection.)^  ^(S
14cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14ce0 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74  KASIDE.** sets t
14cf0 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  he <i>default</i
14d00 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
14d10 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
14d20 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14d30 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b  ].** option to [
14d40 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14d50 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
14d60 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
14d70 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
14d80 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
14d90 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
14da0 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
14db0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14dc0 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
14dd0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
14de0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
14df0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14e00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
14e10 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14e20 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14e30 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
14e40 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14e50 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14e60 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
14e70 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
14e80 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65  fies.** the inte
14e90 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f  rface to a custo
14ea0 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
14eb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a  lementation.)^.*
14ec0 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  * ^SQLite makes 
14ed0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
14ee0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14ef0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c  thods2] object.<
14f00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14f10 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14f20 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14f30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14f40 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14f50 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14f60 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14f70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14f80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14f90 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
14fa0 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14fb0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14fc0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
14fd0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a  QLite copies of.
14fe0 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70  ** the current p
14ff0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
15000 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
15010 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
15020 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15030 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
15040 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15050 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
15060 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
15070 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
15080 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
15090 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
150a0 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
150b0 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
150c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
150d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
150e0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
150f0 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
15100 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
15110 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
15120 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
15130 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
15140 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
15150 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
15160 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
15170 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
15180 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
15190 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
151a0 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
151b0 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
151c0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
151d0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
151e0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
151f0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
15200 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
15210 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
15220 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
15230 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
15240 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
15250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15260 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
15270 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
15280 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15290 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
152a0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
152b0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
152c0 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
152d0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
152e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
152f0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
15300 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
15310 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
15320 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15330 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
15340 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
15350 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
15360 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
15370 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
15380 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
15390 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
153a0 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
153b0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
153c0 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
153d0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
153e0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
153f0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
15400 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
15410 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
15420 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
15430 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
15440 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
15450 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
15460 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
15470 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
15480 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
15490 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
154a0 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
154b0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
154c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
154d0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
154e0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
154f0 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
15500 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15510 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
15520 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15530 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
15540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
15550 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15560 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
15570 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49  f type int..** I
15580 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
15590 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
155a0 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
155b0 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
155c0 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20  ter is zero,.** 
155d0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
155e0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  g is globally di
155f0 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
15600 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15610 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65  obally.** enable
15620 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
15630 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
15640 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
15650 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
15660 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
15670 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
15680 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
15690 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
156a0 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
156b0 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
156c0 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
156d0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
156e0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
156f0 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
15700 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
15710 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
15720 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
15730 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
15740 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
15750 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
15760 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
15770 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
15780 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
15790 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
157a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
157b0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
157c0 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
157d0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
157e0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
157f0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
15800 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
15810 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
15820 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
15830 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
15840 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
15850 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15860 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
15870 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
15880 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
15890 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
158a0 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  AN.** <dd>^The S
158b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
158c0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
158d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
158e0 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a  single integer.*
158f0 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  * argument which
15900 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
15910 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  as a boolean in 
15920 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
15930 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  or disable.** th
15940 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
15950 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
15960 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
15970 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
15980 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64  mizer..** ^The d
15990 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
159a0 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
159b0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
159c0 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
159d0 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
159e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
159f0 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
15a00 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
15a10 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
15a20 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
15a30 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
15a40 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15a50 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15a60 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
15a70 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
15a80 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
15a90 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
15aa0 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
15ab0 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68  alfunction.** wh
15ac0 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
15ad0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
15ae0 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
15af0 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
15b00 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
15b10 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
15b20 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
15b30 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
15b40 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
15b50 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
15b60 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
15b70 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
15b80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15b90 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
15ba0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15bb0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
15bc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15bd0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
15be0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
15bf0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
15c00 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
15c10 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
15c20 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
15c30 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
15c40 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
15c50 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15c60 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
15c70 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
15c80 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15c90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
15ca0 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
15cb0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
15cc0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
15cd0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
15ce0 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
15cf0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
15d00 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
15d10 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
15d20 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
15d30 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
15d40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
15d50 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
15d60 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
15d70 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
15d80 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
15d90 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
15da0 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
15db0 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
15dc0 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
15dd0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
15de0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
15df0 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
15e00 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
15e10 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
15e20 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
15e30 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
15e40 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
15e50 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
15e60 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
15e70 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
15e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
15e90 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
15ea0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15eb0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
15ec0 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
15ed0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
15ee0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
15ef0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
15f00 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
15f10 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
15f20 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15f30 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
15f40 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
15f50 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
15f60 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
15f70 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
15f80 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
15f90 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
15fa0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15fb0 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
15fc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
15fd0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
15fe0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15ff0 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
16000 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
16010 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
16020 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
16030 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
16040 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
16050 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16060 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
16070 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
16080 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
16090 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
160a0 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
160b0 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
160c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
160d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
160e0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
160f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
16100 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51  _SIZE.** <dd>^SQ
16110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
16120 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
16130 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
16140 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
16150 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
16160 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
16170 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
16180 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
16190 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
161a0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
161b0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
161c0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
161d0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64  limit..** ^The d
161e0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63  efault setting c
161f0 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
16200 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73   by each databas
16210 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
16220 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65  ng.** either the
16230 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
16240 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20  ze] command, or 
16250 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  by using the.** 
16260 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
16270 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
16280 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61  ntrol.  ^(The ma
16290 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
162a0 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20  ap size.** will 
162b0 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  be silently trun
162c0 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61  cated if necessa
162d0 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f  ry so that it do
162e0 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68  es not exceed th
162f0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  e.** compile-tim
16300 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73  e maximum mmap s
16310 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a  ize set by the.*
16320 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d  * [SQLITE_MAX_MM
16330 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65  AP_SIZE] compile
16340 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a  -time option.)^.
16350 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72  ** ^If either ar
16360 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f  gument to this o
16370 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76  ption is negativ
16380 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67  e, then that arg
16390 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e  ument is.** chan
163a0 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69  ged to its compi
163b0 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e  le-time default.
163c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
163d0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
163e0 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PSIZE]].** <dt>S
163f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16400 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c  32_HEAPSIZE.** <
16410 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16420 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16430 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f  SIZE option is o
16440 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
16450 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
16460 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f  mpiled for Windo
16470 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ws with the [SQL
16480 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
16490 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
164a0 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64  macro.** defined
164b0 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  . ^SQLITE_CONFIG
164c0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
164d0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
164e0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
164f0 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
16500 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
16510 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
16520 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
16530 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16540 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
16550 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16560 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16570 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
16580 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16590 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
165a0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
165b0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
165c0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
165d0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
165e0 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
165f0 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
16600 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
16610 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
16620 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
16630 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
16640 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16650 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61  CACHE]..** The a
16660 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73  mount of extra s
16670 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
16680 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
16690 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
166a0 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
166b0 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
166c0 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  te version..**.*
166d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
166e0 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  G_PMASZ]].** <dt
166f0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
16700 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  MASZ.** <dd>^The
16710 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16720 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  MASZ option take
16730 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16740 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16750 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   an unsigned int
16760 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68  eger and sets th
16770 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  e "Minimum PMA S
16780 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c  ize" for the mul
16790 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f  tithreaded.** so
167a0 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74  rter to that int
167b0 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  eger.  The defau
167c0 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  lt minimum PMA S
167d0 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68  ize is set by th
167e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52  e.** [SQLITE_SOR
167f0 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69  TER_PMASZ] compi
16800 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
16810 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65   New threads are
16820 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20   launched.** to 
16830 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f  help with sort o
16840 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d  perations when m
16850 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72  ultithreaded sor
16860 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c  ting.** is enabl
16870 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50  ed (using the [P
16880 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63  RAGMA threads] c
16890 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20  ommand) and the 
168a0 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e  amount of conten
168b0 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65  t.** to be sorte
168c0 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61  d exceeds the pa
168d0 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68  ge size times th
168e0 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65  e minimum of the
168f0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68  .** [PRAGMA cach
16900 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20  e_size] setting 
16910 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a  and this value..
16920 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16930 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16940 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  PILL]].** <dt>SQ
16950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16960 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64  JRNL_SPILL.** <d
16970 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16980 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
16990 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ILL option takes
169a0 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
169b0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63  ter which.** bec
169c0 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d  omes the [statem
169d0 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69  ent journal] spi
169e0 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73  ll-to-disk thres
169f0 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74  hold.  .** [Stat
16a00 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20  ement journals] 
16a10 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f  are held in memo
16a20 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73  ry until their s
16a30 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a  ize (in bytes).*
16a40 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74  * exceeds this t
16a50 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69  hreshold, at whi
16a60 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72  ch point they ar
16a70 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  e written to dis
16a80 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20  k..** Or if the 
16a90 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c  threshold is -1,
16aa0 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
16ab0 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68  als are always h
16ac0 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65  eld.** exclusive
16ad0 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ly in memory..**
16ae0 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74   Since many stat
16af0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e  ement journals n
16b00 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67  ever become larg
16b10 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73  e, setting the s
16b20 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c  pill.** threshol
16b30 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63  d to a value suc
16b40 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67  h as 64KiB can g
16b50 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68  reatly reduce th
16b60 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49  e amount of.** I
16b70 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73  /O required to s
16b80 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74  upport statement
16b90 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   rollback..** Th
16ba0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
16bb0 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67  for this setting
16bc0 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62   is controlled b
16bd0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16be0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
16bf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16c00 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  tion..** </dl>.*
16c10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16c20 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
16c30 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
16c40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16c50 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
16c60 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
16c70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16c80 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
16c90 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
16ca0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
16cb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
16cc0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
16cd0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16ce0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16d00 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
16d10 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
16d20 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
16d30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16d40 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
16d50 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
16d60 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16d70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16d80 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
16d90 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
16da0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
16db0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16dc0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
16dd0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
16de0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
16df0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e00 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
16e10 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
16e20 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
16e30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16e40 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
16e50 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
16e60 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16e70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16e80 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
16e90 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
16ea0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
16eb0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
16ec0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
16ed0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
16ee0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
16ef0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
16f00 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16f10 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
16f20 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
16f30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16f40 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
16f50 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16f60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16f70 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
16f80 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
16f90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16fa0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
16fb0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
16fc0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
16fd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
16fe0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
16ff0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
17000 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17010 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
17020 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
17030 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
17040 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17050 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
17060 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
17070 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17080 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
170a0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
170b0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
170c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
170d0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
170e0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
170f0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
17100 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17110 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
17120 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
17130 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
17140 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17150 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17160 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
17170 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
17180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17190 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
171a0 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
171b0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
171c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
171d0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
171e0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
171f0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
17200 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ma */.#define SQ
17210 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
17220 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20  JRNL_SPILL      
17230 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  26  /* int nByte
17240 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
17250 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
17260 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
17270 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
17280 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
17290 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
172a0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
172b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
172c0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
172d0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
172e0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
172f0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
17300 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
17310 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
17320 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
17330 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
17340 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
17350 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
17360 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
17370 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17380 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
17390 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
173a0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
173b0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
173c0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
173d0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
173e0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
173f0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
17400 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
17410 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
17420 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
17430 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
17440 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
17450 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
17460 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
17470 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
17480 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
17490 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
174a0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
174b0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
174c0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
174d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
174e0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
174f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
17500 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
17510 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
17520 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
17530 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
17540 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
17550 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17560 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
17570 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
17580 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17590 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
175a0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
175b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
175c0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
175d0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
175e0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
175f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17600 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
17610 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
17620 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
17630 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
17640 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
17650 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
17660 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
17670 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
17680 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
17690 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
176a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
176b0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
176c0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
176d0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
176e0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
176f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
17700 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
17710 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
17720 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
17730 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
17740 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
17750 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
17760 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
17770 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
17780 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
17790 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
177a0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
177b0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
177c0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
177d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
177e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
177f0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
17800 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
17810 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
17820 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
17830 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
17840 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
17850 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
17860 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
17870 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17880 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
17890 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
178a0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
178b0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
178c0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
178d0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
178e0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
178f0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
17900 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
17910 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
17920 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
17930 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
17940 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
17950 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
17960 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
17970 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
17980 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
17990 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
179a0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
179b0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
179c0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
179d0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
179e0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
179f0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
17a00 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
17a10 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
17a20 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17a30 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
17a40 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17a50 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17a60 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17a70 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
17a80 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
17a90 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
17aa0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17ab0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17ac0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17ad0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17ae0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17af0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17b00 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
17b10 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
17b20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
17b30 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
17b40 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
17b50 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
17b60 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
17b70 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17b80 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17b90 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17ba0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17bb0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17bc0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17bd0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
17be0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
17bf0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17c00 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17c10 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17c20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17c30 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17c40 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
17c50 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
17c60 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17c70 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17c80 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17c90 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
17ca0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
17cb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17cc0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17cd0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
17ce0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
17cf0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
17d00 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17d10 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17d20 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17d30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17d40 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17d50 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
17d60 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
17d70 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
17d80 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
17d90 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
17da0 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
17db0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
17dc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
17dd0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17de0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
17df0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17e00 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17e10 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
17e20 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
17e30 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
17e40 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17e50 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17e60 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17e70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17e80 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17e90 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
17ea0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17eb0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17ec0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17ed0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17ee0 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c  _FTS3_TOKENIZER<
17ef0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17f00 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
17f10 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17f20 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61  isable the two-a
17f30 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69  rgument.** versi
17f40 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f  on of the [fts3_
17f50 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e  tokenizer()] fun
17f60 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70  ction which is p
17f70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46  art of the.** [F
17f80 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73  TS3] full-text s
17f90 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74  earch engine ext
17fa0 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  ension..** There
17fb0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
17fc0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17fd0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
17fe0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17ff0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18000 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66  s 0 to disable f
18010 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
18020 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  or.** positive t
18030 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f  o enable fts3_to
18040 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67  kenizer() or neg
18050 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
18060 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e  he setting.** un
18070 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
18080 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18090 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
180a0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
180b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
180c0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
180d0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
180e0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69  fts3_tokenizer i
180f0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
18100 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
18110 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
18120 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18130 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
18140 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
18150 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18160 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
18170 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18180 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
18190 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
181a0 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
181b0 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20  TENSION</dt>.** 
181c0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
181d0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
181e0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
181f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
18200 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a  _extension()].**
18210 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70   interface indep
18220 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20  endently of the 
18230 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
18240 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  )] SQL function.
18250 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
18260 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
18270 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e  ension()] API en
18280 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
18290 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d  s both the.** C-
182a0 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  API [sqlite3_loa
182b0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61  d_extension()] a
182c0 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
182d0 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73  ion [load_extens
182e0 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65  ion()]..** There
182f0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
18300 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18310 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65  nts..** When the
18320 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18330 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  to this interfac
18340 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c  e is 1, then onl
18350 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a  y the C-API is.*
18360 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68  * enabled and th
18370 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
18380 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e  emains disabled.
18390 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61    If the first a
183a0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
183b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
183c0 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65  0, then both the
183d0 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53   C-API and the S
183e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  QL function are 
183f0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20  disabled..** If 
18400 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18410 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e  nt is -1, then n
18420 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61  o changes are ma
18430 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65  de to state of e
18440 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41  ither the.** C-A
18450 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75  PI or the SQL fu
18460 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73  nction..** The s
18470 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18480 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18490 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
184a0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
184b0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
184c0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b  dicate whether [
184d0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
184e0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
184f0 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c  ace.** is disabl
18500 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f  ed or enabled fo
18510 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
18520 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18530 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20  arameter may.** 
18540 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
18550 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  r, in which case
18560 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67   the new setting
18570 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
18580 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   back..** </dd>.
18590 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
185a0 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
185b0 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NAME</dt>.** <dd
185c0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
185d0 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  s used to change
185e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
185f0 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65   "main" database
18600 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68  .** schema.  ^Th
18610 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20  e sole argument 
18620 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18630 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20  a constant UTF8 
18640 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20  string.** which 
18650 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
18660 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  new schema name 
18670 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69  in place of "mai
18680 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  n".  ^SQLite.** 
18690 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20  does not make a 
186a0 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20  copy of the new 
186b0 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65  main schema name
186c0 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20   string, so the 
186d0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
186e0 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
186f0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73  the argument pas
18700 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42  sed into this DB
18710 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73  CONFIG option is
18720 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e   unchanged.** un
18730 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61  til after the da
18740 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18750 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64  n closes..** </d
18760 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18770 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
18780 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64  CKPT_ON_CLOSE</d
18790 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c  t>.** <dd> Usual
187a0 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62  ly, when a datab
187b0 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20  ase in wal mode 
187c0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74  is closed or det
187d0 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a  ached from a .**
187e0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
187f0 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20  , SQLite checks 
18800 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61  if this will mea
18810 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65  n that there are
18820 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e   now no .** conn
18830 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74  ections at all t
18840 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  o the database. 
18850 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72  If so, it perfor
18860 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20  ms a checkpoint 
18870 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65  .** operation be
18880 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65  fore closing the
18890 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69   connection. Thi
188a0 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20  s option may be 
188b0 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72  used to.** overr
188c0 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f  ide this behavio
188d0 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61  ur. The first pa
188e0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
188f0 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e  o this operation
18900 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
18910 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20  r - non-zero to 
18920 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69  disable checkpoi
18930 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72  nts-on-close, or
18940 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65   zero (the.** de
18950 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65  fault) to enable
18960 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e   them. The secon
18970 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18980 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18990 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77  nteger.** into w
189a0 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20  hich is written 
189b0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
189c0 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b  te whether check
189d0 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a  points-on-close.
189e0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73  ** have been dis
189f0 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65  abled - 0 if the
18a00 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c  y are not disabl
18a10 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72  ed, 1 if they ar
18a20 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  e..** </dd>.**.*
18a30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18a40 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
18a50 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
18a60 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18a70 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70  G_ENABLE_QPSG op
18a80 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f  tion activates o
18a90 72 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a  r deactivates.**
18aa0 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e   the [query plan
18ab0 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20 67 75  ner stability gu
18ac0 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e  arantee] (QPSG).
18ad0 20 20 57 68 65 6e 20 74 68 65 20 51 50 53 47 20    When the QPSG 
18ae0 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20  is active,.** a 
18af0 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79  single SQL query
18b00 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
18b10 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73  always use the s
18b20 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65  ame algorithm re
18b30 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76  gardless.** of v
18b40 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20  alues of [bound 
18b50 70 61 72 61 6d 65 74 65 72 73 5d 2e 20 20 54 68  parameters].  Th
18b60 65 20 51 50 53 47 20 64 69 73 61 62 6c 65 73 20  e QPSG disables 
18b70 73 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d  some query optim
18b80 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  izations.** that
18b90 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c   look at the val
18ba0 75 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72  ues of bound par
18bb0 61 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20 63  ameters, which c
18bc0 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65  an make some que
18bd0 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20  ries.** slower. 
18be0 20 42 75 74 20 74 68 65 20 51 50 53 47 20 68 61   But the QPSG ha
18bf0 73 20 74 68 65 20 61 64 76 61 6e 74 61 67 65 20  s the advantage 
18c00 6f 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61  of more predicta
18c10 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57  ble behavior.  W
18c20 69 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20  ith.** the QPSG 
18c30 61 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77  active, SQLite w
18c40 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74  ill always use t
18c50 68 65 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c  he same query pl
18c60 61 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20  an in the field 
18c70 61 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64  as.** was used d
18c80 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e  uring testing in
18c90 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 3c 2f 64   the lab..** </d
18ca0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
18cb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18cc0 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
18cd0 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
18ce0 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68  1000 /* const ch
18cf0 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ar* */.#define S
18d00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18d10 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20  OOKASIDE        
18d20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69       1001 /* voi
18d30 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
18d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18d50 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
18d60 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32  Y           1002
18d70 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18d90 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
18da0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30  RIGGER        10
18db0 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  03 /* int int* *
18dc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18dd0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18de0 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20  _FTS3_TOKENIZER 
18df0 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1004 /* int int*
18e00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18e20 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
18e30 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e  N 1005 /* int in
18e40 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18e50 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
18e60 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20  _CKPT_ON_CLOSE  
18e70 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20      1006 /* int 
18e80 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18e90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18ea0 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20  ENABLE_QPSG     
18eb0 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e        1007 /* in
18ec0 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
18ed0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
18ee0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
18ef0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
18f00 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
18f10 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
18f20 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
18f30 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
18f40 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
18f50 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
18f60 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
18f70 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
18f80 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
18f90 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
18fa0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
18fb0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
18fc0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
18fd0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
18fe0 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
18ff0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
19000 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
19010 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
19020 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19030 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
19040 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
19050 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
19060 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
19070 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
19080 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
19090 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
190a0 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
190b0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
190c0 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
190d0 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
190e0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
190f0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
19100 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
19110 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
19120 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
19130 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
19140 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
19150 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
19160 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
19170 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
19180 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
19190 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
191a0 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
191b0 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
191c0 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
191d0 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
191e0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
191f0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
19200 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19210 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19220 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
19230 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73   usually returns
19240 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a   the [rowid] of.
19250 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
19260 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
19270 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
19280 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
19290 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
192a0 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
192b0 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72  ection D. ^Inser
192c0 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
192d0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
192e0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64  re not.** record
192f0 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  ed. ^If no succe
19300 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
19310 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
19320 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
19330 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20  rred .** on the 
19340 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19350 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69  ion D, then sqli
19360 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19370 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
19380 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a   .** zero..**.**
19390 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e   As well as bein
193a0 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61  g set automatica
193b0 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20  lly as rows are 
193c0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61  inserted into da
193d0 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73  tabase.** tables
193e0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
193f0 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
19400 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74  ction may be set
19410 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a   explicitly by.*
19420 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  * [sqlite3_set_l
19430 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19440 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76  ()].**.** Some v
19450 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
19460 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
19470 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74   INSERT rows int
19480 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61  o rowid tables a
19490 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d  s.** part of com
194a0 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61  mitting a transa
194b0 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66  ction (e.g. to f
194c0 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75  lush data accumu
194d0 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  lated in memory.
194e0 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20  ** to disk). In 
194f0 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71  this case subseq
19500 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68  uent calls to th
19510 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
19520 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20  rn the rowid.** 
19530 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
19540 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49  these internal I
19550 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73  NSERT operations
19560 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f  , which leads to
19570 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65   .** unintuitive
19580 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61   results. Virtua
19590 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
195a0 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20  tations that do 
195b0 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a  write to rowid.*
195c0 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73  * tables in this
195d0 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74   way can avoid t
195e0 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72  his problem by r
195f0 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69  estoring the ori
19600 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20  ginal .** rowid 
19610 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c  value using [sql
19620 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
19630 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65  sert_rowid()] be
19640 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a  fore returning .
19650 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68  ** control to th
19660 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e user..**.** ^(
19670 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
19680 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
19690 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73  rigger then this
196a0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a   routine will .*
196b0 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  * return the [ro
196c0 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
196d0 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67  rted row as long
196e0 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
196f0 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20  is .** running. 
19700 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  Once the trigger
19710 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74   program ends, t
19720 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19730 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
19740 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
19750 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
19760 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
19770 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  was fired.)^.**.
19780 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
19790 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
197a0 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
197b0 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
197c0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
197d0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
197e0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
197f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19800 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
19810 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
19820 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
19830 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
19840 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
19850 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
19860 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
19870 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
19880 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
19890 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
198a0 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
198b0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
198c0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
198d0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
198e0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
198f0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
19900 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
19910 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
19920 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
19930 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
19940 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
19950 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
19960 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
19970 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
19980 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
19990 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
199a0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
199b0 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
199c0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
199d0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
199e0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
199f0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
19a00 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
19a10 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
19a20 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
19a30 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
19a40 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
19a50 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
19a60 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
19a70 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
19a80 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19a90 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
19aa0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
19ab0 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
19ac0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
19ad0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
19ae0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
19af0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
19b00 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
19b10 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
19b20 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
19b30 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
19b40 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
19b50 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
19b60 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
19b70 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
19b80 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19b90 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
19ba0 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
19bb0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
19bc0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
19bd0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
19be0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19bf0 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
19c00 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
19c10 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19c20 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19c30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
19c40 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74   the Last Insert
19c50 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a   Rowid value..**
19c60 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
19c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
19c80 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
19c90 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d  rt_rowid(D, R) m
19ca0 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65  ethod allows the
19cb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
19cc0 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ** set the value
19cd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c   returned by cal
19ce0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73  ling sqlite3_las
19cf0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
19d00 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f  ) to R .** witho
19d10 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72  ut inserting a r
19d20 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  ow into the data
19d30 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  base..*/.void sq
19d40 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
19d50 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
19d60 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  te3*,sqlite3_int
19d70 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
19d80 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
19d90 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
19da0 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
19db0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19dc0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
19dd0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
19de0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
19df0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
19e00 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
19e10 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
19e20 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
19e30 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
19e40 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
19e50 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
19e60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
19e70 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
19e80 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
19e90 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
19ea0 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
19eb0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
19ec0 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
19ed0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
19ee0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
19ef0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
19f00 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
19f10 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
19f20 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
19f30 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
19f40 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
19f50 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
19f60 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
19f70 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
19f80 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
19f90 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
19fa0 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
19fb0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
19fc0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
19fd0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
19fe0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
19ff0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1a000 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
1a010 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1a020 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
1a030 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
1a040 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
1a050 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
1a060 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1a070 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
1a080 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
1a090 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
1a0a0 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
1a0b0 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
1a0c0 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
1a0d0 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
1a0e0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
1a0f0 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
1a100 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
1a110 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
1a120 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
1a130 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1a140 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
1a150 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
1a160 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
1a170 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
1a180 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
1a190 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
1a1a0 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
1a1b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
1a1c0 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
1a1d0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1a1e0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
1a1f0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1a200 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
1a210 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
1a220 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
1a230 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
1a240 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1a250 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a260 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1a270 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a280 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
1a290 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
1a2a0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1a2b0 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
1a2c0 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
1a2d0 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
1a2e0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
1a2f0 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
1a300 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
1a310 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
1a320 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
1a330 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
1a340 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
1a350 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a360 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1a370 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1a380 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
1a390 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
1a3a0 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
1a3b0 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
1a3c0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
1a3d0 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
1a3e0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
1a3f0 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
1a400 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1a410 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
1a420 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
1a430 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
1a440 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
1a450 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
1a460 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
1a470 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
1a480 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
1a490 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
1a4a0 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
1a4b0 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
1a4c0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1a4d0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1a4e0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1a4f0 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
1a500 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
1a510 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
1a520 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
1a530 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
1a540 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
1a550 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1a560 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
1a570 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
1a580 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
1a590 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
1a5a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
1a5b0 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
1a5c0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1a5d0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
1a5e0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
1a5f0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1a600 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1a610 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
1a620 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
1a630 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
1a640 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1a650 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1a660 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1a670 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1a680 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1a690 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1a6a0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1a6b0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1a6c0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1a6d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a6e0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1a6f0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a700 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1a710 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1a720 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
1a730 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1a740 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1a750 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
1a760 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1a770 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a780 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
1a790 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1a7a0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a7b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1a7c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1a7d0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
1a7e0 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
1a7f0 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
1a800 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
1a810 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
1a820 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
1a830 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
1a840 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
1a850 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a860 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
1a870 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
1a880 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
1a890 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
1a8a0 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
1a8b0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1a8c0 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1a8d0 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
1a8e0 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
1a8f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1a900 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a910 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
1a920 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
1a930 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
1a940 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
1a950 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
1a960 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
1a970 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
1a980 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
1a990 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1a9a0 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
1a9b0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1a9c0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1a9d0 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
1a9e0 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
1a9f0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1aa00 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
1aa10 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
1aa20 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1aa30 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1aa40 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1aa50 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
1aa60 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
1aa70 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1aa80 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1aa90 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1aaa0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1aab0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1aac0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1aad0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1aae0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1aaf0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1ab00 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
1ab10 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1ab20 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1ab30 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1ab40 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1ab50 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1ab60 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
1ab70 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
1ab80 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
1ab90 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1aba0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1abb0 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
1abc0 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
1abd0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
1abe0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
1abf0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
1ac00 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
1ac10 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
1ac20 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
1ac30 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
1ac40 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
1ac50 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
1ac60 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
1ac70 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
1ac80 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
1ac90 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
1aca0 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
1acb0 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
1acc0 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
1acd0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1ace0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
1acf0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
1ad00 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
1ad10 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
1ad20 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
1ad30 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
1ad40 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
1ad50 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1ad60 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
1ad70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ad80 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
1ad90 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
1ada0 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
1adb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1adc0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
1add0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
1ade0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
1adf0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
1ae00 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
1ae10 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
1ae20 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
1ae30 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
1ae40 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
1ae50 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
1ae60 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
1ae70 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
1ae80 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
1ae90 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
1aea0 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
1aeb0 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
1aec0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
1aed0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
1aee0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
1aef0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1af00 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
1af10 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
1af20 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
1af30 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
1af40 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
1af50 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
1af60 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
1af70 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
1af80 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
1af90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
1afa0 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
1afb0 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
1afc0 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
1afd0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
1afe0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
1aff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b000 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
1b010 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
1b020 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1b030 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1b040 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1b050 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1b060 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
1b070 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
1b080 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
1b090 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
1b0a0 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
1b0b0 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
1b0c0 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
1b0d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b0e0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
1b0f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b100 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1b110 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
1b120 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
1b130 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
1b140 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
1b150 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
1b160 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b170 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
1b180 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b190 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
1b1a0 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
1b1b0 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
1b1c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
1b1d0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
1b1e0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
1b1f0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1b200 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1b210 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1b220 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1b230 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76  ll returns..*/.v
1b240 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1b250 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1b260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b270 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1b280 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1b290 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1b2a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b2b0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1b2c0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1b2d0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1b2e0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1b2f0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1b300 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1b310 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1b320 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1b330 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1b340 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1b350 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1b360 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1b370 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1b380 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1b390 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1b3a0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1b3b0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1b3c0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1b3d0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1b3e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1b3f0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1b400 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1b410 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1b420 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1b430 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1b440 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1b450 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1b460 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1b470 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1b480 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1b490 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1b4a0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1b4b0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1b4c0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1b4d0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1b4e0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1b4f0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1b500 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1b510 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1b520 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1b530 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1b540 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1b550 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1b560 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1b570 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1b580 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1b590 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1b5a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1b5b0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1b5c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1b5d0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1b5e0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1b5f0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1b600 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1b610 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1b620 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1b630 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1b640 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1b650 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1b660 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1b670 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1b680 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1b690 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1b6a0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1b6b0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1b6c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1b6d0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1b6e0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1b6f0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1b700 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1b710 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1b720 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1b730 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1b740 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1b750 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1b760 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1b770 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1b780 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1b790 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1b7a0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1b7b0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1b7c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1b7d0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1b7e0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1b7f0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1b800 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b810 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1b820 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1b830 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1b840 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1b850 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1b860 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1b870 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1b880 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1b890 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1b8a0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
1b8b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1b8c0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1b8d0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1b8e0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1b8f0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1b900 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1b910 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1b920 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1b930 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1b940 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1b950 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1b960 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1b970 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1b980 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1b990 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1b9a0 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1b9b0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1b9c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1b9d0 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1b9e0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1b9f0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1ba00 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1ba10 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1ba20 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1ba30 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1ba40 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1ba50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1ba60 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1ba70 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1ba80 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1ba90 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1baa0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1bab0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1bac0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1bad0 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1bae0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1baf0 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1bb00 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1bb10 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1bb20 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1bb30 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1bb40 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1bb50 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1bb60 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1bb70 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1bb80 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1bb90 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1bba0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1bbb0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1bbc0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1bbd0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1bbe0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1bbf0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1bc00 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1bc10 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1bc20 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1bc30 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1bc40 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1bc50 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1bc60 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1bc70 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1bc80 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1bc90 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1bca0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1bcb0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1bcc0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1bcd0 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1bce0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1bcf0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1bd00 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1bd10 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1bd20 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1bd30 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1bd40 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1bd50 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1bd60 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1bd70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1bd80 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1bd90 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1bda0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1bdb0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1bdc0 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1bdd0 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1bde0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1bdf0 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1be00 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1be10 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1be20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1be30 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1be40 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1be50 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1be60 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1be70 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1be80 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1be90 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1bea0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1beb0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1bec0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1bed0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1bee0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1bef0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1bf00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1bf10 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1bf20 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1bf30 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1bf40 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1bf50 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1bf60 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1bf70 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1bf80 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1bf90 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1bfa0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1bfb0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1bfc0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1bfd0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1bfe0 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1bff0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1c000 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1c010 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1c020 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1c030 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1c040 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1c050 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1c060 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1c070 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1c080 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1c090 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1c0a0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1c0b0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1c0c0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1c0d0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1c0e0 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1c0f0 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1c100 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1c110 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1c120 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1c130 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1c140 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1c150 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1c160 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1c170 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1c180 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1c190 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1c1a0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1c1b0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1c1c0 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1c1d0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1c1e0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1c1f0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1c200 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1c210 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1c220 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c230 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1c240 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1c250 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1c260 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1c270 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1c280 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1c290 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1c2a0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1c2b0 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1c2c0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1c2d0 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1c2e0 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1c2f0 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1c300 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1c310 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1c320 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1c330 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1c340 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1c350 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1c360 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1c370 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c380 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1c390 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1c3a0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1c3b0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1c3c0 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1c3d0 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1c3e0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1c3f0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1c400 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1c410 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1c420 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1c430 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c440 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1c450 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c460 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1c470 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1c480 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1c490 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1c4a0 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1c4b0 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1c4c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c4d0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1c4e0 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1c4f0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1c500 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1c510 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1c520 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1c530 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1c540 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1c550 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1c560 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1c570 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1c580 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1c590 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1c5a0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1c5b0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1c5c0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1c5d0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1c5e0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1c5f0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1c600 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1c610 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1c620 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1c630 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1c640 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c650 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1c660 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1c670 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1c680 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1c690 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1c6a0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1c6b0 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1c6c0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1c6d0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1c6e0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1c6f0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1c700 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1c710 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1c720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1c730 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1c740 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1c750 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1c760 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1c770 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1c780 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1c790 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1c7a0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1c7b0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1c7c0 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1c7d0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1c7e0 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1c7f0 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1c800 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1c810 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1c820 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1c830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1c840 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1c850 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1c860 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1c870 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1c880 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1c890 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1c8a0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1c8b0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1c8c0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1c8d0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1c8e0 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1c8f0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1c900 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1c910 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1c920 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1c930 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1c940 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1c950 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1c960 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1c970 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1c980 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1c990 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1c9a0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1c9b0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1c9c0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1c9d0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1c9e0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1c9f0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1ca00 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1ca10 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1ca20 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1ca30 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1ca40 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1ca50 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1ca60 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1ca70 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1ca80 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1ca90 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1caa0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1cab0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1cac0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1cad0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1cae0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1caf0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1cb00 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1cb10 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1cb20 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1cb30 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1cb40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1cb50 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1cb60 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1cb70 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1cb80 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1cb90 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1cba0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1cbb0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1cbc0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1cbd0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1cbe0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1cbf0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1cc00 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1cc10 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1cc20 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1cc30 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1cc40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1cc50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1cc60 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1cc70 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1cc80 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1cc90 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1cca0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1ccb0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1ccc0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1ccd0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1cce0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1ccf0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1cd00 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1cd10 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1cd20 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1cd30 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1cd40 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1cd50 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1cd60 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1cd70 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1cd80 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1cd90 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1cda0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1cdb0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1cdc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cdd0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1cde0 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1cdf0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1ce00 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1ce10 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1ce20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1ce30 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1ce40 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1ce50 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1ce60 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1ce70 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1ce80 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1ce90 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1cea0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1ceb0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1cec0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1ced0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1cee0 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1cef0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1cf00 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1cf10 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cf20 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1cf30 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1cf40 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1cf50 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1cf60 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1cf70 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1cf80 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1cf90 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cfa0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1cfb0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cfc0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1cfd0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1cfe0 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1cff0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d000 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1d010 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1d020 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1d030 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1d040 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1d050 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1d060 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d070 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1d080 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1d090 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1d0a0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1d0b0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1d0c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1d0d0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1d0e0 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1d0f0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1d100 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1d110 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1d120 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1d130 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1d140 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1d150 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1d160 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1d170 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1d180 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1d190 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1d1a0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d1b0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1d1c0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1d1d0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1d1e0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1d1f0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1d200 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1d210 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1d220 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d230 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1d240 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1d250 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1d260 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1d270 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1d280 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1d290 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1d2a0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1d2b0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1d2c0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1d2d0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1d2e0 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1d2f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1d300 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1d310 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1d320 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1d330 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1d340 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1d350 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1d360 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1d370 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1d380 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1d390 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1d3a0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1d3b0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1d3c0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1d3d0 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1d3e0 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1d3f0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1d400 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1d410 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1d420 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1d430 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1d440 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1d450 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1d460 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1d470 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1d480 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1d490 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1d4a0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1d4b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1d4c0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1d4d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1d4e0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1d4f0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1d500 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1d510 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1d520 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1d530 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1d540 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1d550 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1d560 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1d570 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1d580 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1d590 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1d5a0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1d5b0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1d5c0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1d5d0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1d5e0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1d5f0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1d600 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1d610 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
1d620 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d630 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1d640 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d650 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1d660 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1d670 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1d680 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1d690 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1d6a0 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1d6b0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1d6c0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1d6d0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1d6e0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1d6f0 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1d700 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1d710 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67  n K&R formatting
1d720 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75   options,.** plu
1d730 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1d740 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1d750 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64  ormats, detailed
1d760 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20   below..** Note 
1d770 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65  that some of the
1d780 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f   more obscure fo
1d790 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1d7a0 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20   from recent.** 
1d7b0 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61  C-library standa
1d7c0 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20  rds are omitted 
1d7d0 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d  from this implem
1d7e0 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  entation..**.** 
1d7f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1d800 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1d810 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1d820 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1d830 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1d840 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1d850 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1d860 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1d870 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1d880 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1d890 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1d8a0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1d8b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1d8c0 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1d8d0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1d8e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1d8f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d900 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1d910 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1d920 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1d930 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1d940 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1d950 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1d960 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1d970 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1d980 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1d990 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1d9a0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1d9b0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1d9c0 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1d9d0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1d9e0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1d9f0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1da00 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1da10 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1da20 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1da30 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1da40 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1da50 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1da60 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1da70 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1da80 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1da90 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1daa0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1dab0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1dac0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1dad0 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1dae0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1daf0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1db00 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1db10 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1db20 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1db30 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1db40 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1db50 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1db60 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1db70 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1db80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1db90 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1dba0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1dbb0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1dbc0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1dbd0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1dbe0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1dbf0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1dc00 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1dc10 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1dc20 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1dc30 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1dc40 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1dc50 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1dc60 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1dc70 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1dc80 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1dc90 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1dca0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1dcb0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1dcc0 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1dcd0 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1dce0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1dcf0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1dd00 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1dd10 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1dd20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1dd30 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1dd40 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1dd50 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1dd60 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1dd70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1dd80 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1dd90 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1dda0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1ddb0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1ddc0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1ddd0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1dde0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1ddf0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1de00 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1de10 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1de20 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1de30 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1de40 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1de50 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1de60 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1de70 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1de80 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1de90 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20  %q", "%Q", "%w" 
1dea0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1deb0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1dec0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1ded0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1dee0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1def0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1df00 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1df10 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1df20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1df30 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1df40 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1df50 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1df60 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1df70 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1df80 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1df90 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1dfa0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1dfb0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1dfc0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1dfd0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1dfe0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1dff0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1e000 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1e010 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1e020 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1e030 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1e040 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e050 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1e060 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1e070 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1e080 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1e090 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1e0a0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1e0b0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1e0c0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1e0d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e0e0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1e0f0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1e100 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1e110 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1e120 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1e130 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1e140 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1e150 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1e160 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1e170 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e180 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1e190 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1e1a0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1e1b0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1e1c0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1e1d0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1e1e0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1e1f0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1e200 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1e210 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1e220 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1e230 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1e240 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1e250 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e260 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1e270 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1e280 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1e290 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1e2a0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1e2b0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1e2c0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1e2d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1e2e0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1e2f0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1e300 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1e310 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1e320 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e330 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1e340 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1e350 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1e360 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1e370 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1e380 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1e390 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1e3a0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1e3b0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1e3c0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1e3d0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1e3e0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1e3f0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1e400 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1e410 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1e420 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1e430 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1e440 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1e450 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1e460 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1e470 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1e480 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1e490 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1e4a0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1e4b0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1e4c0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1e4d0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1e4e0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1e4f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1e500 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1e510 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1e520 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1e530 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1e540 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1e550 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1e560 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1e570 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1e580 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1e590 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1e5a0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1e5b0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1e5c0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1e5d0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1e5e0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1e5f0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1e600 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1e610 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1e620 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1e630 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b  ng option is lik
1e640 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68  e "%q" except th
1e650 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f  at it expects to
1e660 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  .** be contained
1e670 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71   within double-q
1e680 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66  uotes instead of
1e690 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20   single quotes, 
1e6a0 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65  and it.** escape
1e6b0 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f  s the double-quo
1e6c0 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73  te character ins
1e6d0 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67  tead of the sing
1e6e0 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72  le-quote.** char
1e6f0 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25  acter.)^  The "%
1e700 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1e710 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64  tion is intended
1e720 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65   for safely inse
1e730 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61  rting.** table a
1e740 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  nd column names 
1e750 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74  into a construct
1e760 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1e770 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1e780 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1e790 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1e7a0 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1e7b0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1e7c0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1e7d0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1e7e0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1e7f0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1e800 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e810 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1e820 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1e830 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1e840 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1e850 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1e860 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1e870 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1e880 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1e890 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1e8a0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1e8b0 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1e8c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1e8d0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1e8e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1e8f0 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1e900 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1e910 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1e920 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1e930 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1e940 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1e950 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1e960 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1e970 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1e980 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1e990 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1e9a0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1e9b0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1e9c0 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1e9d0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1e9e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1e9f0 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1ea00 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1ea10 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1ea20 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1ea30 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1ea40 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1ea50 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1ea60 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ea70 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1ea80 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1ea90 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1eaa0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1eab0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1eac0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1ead0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1eae0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1eaf0 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1eb00 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1eb10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1eb20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1eb30 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1eb40 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1eb50 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1eb60 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1eb70 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1eb80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1eb90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1eba0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
1ebb0 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
1ebc0 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
1ebd0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
1ebe0 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
1ebf0 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
1ec00 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1ec10 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
1ec20 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
1ec30 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1ec40 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1ec50 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1ec60 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1ec70 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1ec80 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1ec90 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1eca0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1ecb0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1ecc0 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1ecd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1ece0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1ecf0 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1ed00 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1ed10 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1ed20 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1ed30 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1ed40 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1ed50 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1ed60 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1ed70 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1ed80 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1ed90 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1eda0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1edb0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1edc0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1edd0 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1ede0 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1edf0 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1ee00 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1ee10 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1ee20 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1ee30 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1ee40 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1ee50 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1ee60 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1ee70 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1ee80 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1ee90 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1eea0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1eeb0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1eec0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1eed0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1eee0 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
1eef0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1ef00 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1ef10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1ef20 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
1ef30 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
1ef40 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
1ef50 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1ef60 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
1ef70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1ef80 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1ef90 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1efa0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1efb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
1efc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
1efd0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1efe0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1eff0 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1f000 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1f010 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1f020 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1f030 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1f040 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
1f050 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f060 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
1f070 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1f080 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1f090 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1f0a0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1f0b0 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
1f0c0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
1f0d0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1f0e0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1f0f0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1f100 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1f110 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1f120 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1f130 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1f140 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1f150 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1f160 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1f170 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1f180 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
1f190 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1f1a0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1f1b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f1c0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
1f1d0 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
1f1e0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
1f1f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1f200 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1f210 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f220 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
1f230 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
1f240 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
1f250 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f260 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
1f270 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
1f280 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
1f290 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
1f2a0 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
1f2b0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
1f2c0 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
1f2d0 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
1f2e0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
1f2f0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1f300 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1f310 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
1f320 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
1f330 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f340 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
1f350 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1f360 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
1f370 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
1f380 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
1f390 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
1f3a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1f3b0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
1f3c0 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
1f3d0 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
1f3e0 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
1f3f0 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
1f400 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
1f410 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
1f420 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
1f430 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1f440 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
1f450 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
1f460 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
1f470 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
1f480 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
1f490 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
1f4a0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
1f4b0 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
1f4c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f4d0 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
1f4e0 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
1f4f0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
1f500 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
1f510 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
1f520 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
1f530 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
1f540 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
1f550 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1f560 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
1f570 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1f580 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1f590 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1f5a0 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
1f5b0 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1f5c0 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1f5d0 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1f5e0 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1f5f0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1f600 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1f610 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1f620 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1f630 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1f640 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1f650 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1f660 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1f670 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1f680 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1f690 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1f6a0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1f6b0 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1f6c0 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1f6d0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1f6e0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1f6f0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1f700 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1f710 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1f720 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1f730 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1f740 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1f750 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1f760 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1f770 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1f780 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1f790 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1f7a0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1f7b0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1f7c0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1f7d0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1f7e0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1f7f0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1f800 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1f810 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1f820 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1f830 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1f840 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1f850 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1f860 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1f870 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1f880 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1f890 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1f8a0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1f8b0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1f8c0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1f8d0 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1f8e0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1f8f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1f900 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1f910 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f920 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1f930 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1f940 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1f950 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1f960 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1f970 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1f980 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1f990 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1f9a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f9b0 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1f9c0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1f9d0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1f9e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1f9f0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1fa00 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1fa10 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1fa20 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1fa30 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1fa40 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1fa50 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1fa60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1fa70 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1fa80 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1fa90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1faa0 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
1fab0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
1fac0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1fad0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
1fae0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1faf0 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
1fb00 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1fb10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1fb20 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
1fb30 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
1fb40 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1fb50 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1fb60 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1fb70 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1fb80 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1fb90 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1fba0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1fbb0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1fbc0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1fbd0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1fbe0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1fbf0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1fc00 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1fc10 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1fc20 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1fc30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1fc40 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1fc50 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1fc60 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1fc70 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1fc80 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1fc90 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1fca0 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1fcb0 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1fcc0 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1fcd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1fce0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1fcf0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1fd00 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1fd10 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1fd20 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1fd30 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1fd40 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1fd50 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1fd60 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1fd70 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1fd80 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1fd90 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1fda0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1fdb0 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1fdc0 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1fdd0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1fde0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1fdf0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1fe00 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1fe10 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1fe20 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1fe30 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1fe40 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1fe50 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1fe60 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1fe70 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1fe80 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1fe90 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1fea0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1feb0 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1fec0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1fed0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1fee0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1fef0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1ff00 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1ff10 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1ff20 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1ff30 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1ff40 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1ff50 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1ff60 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1ff70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1ff80 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
1ff90 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1ffa0 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
1ffb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1ffc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1ffd0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1ffe0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1fff0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
20000 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
20010 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
20020 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
20030 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
20040 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
20050 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
20060 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
20070 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
20080 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
20090 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
200a0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
200b0 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
200c0 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
200d0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
200e0 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
200f0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
20100 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
20110 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
20120 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
20130 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
20140 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
20150 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
20160 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
20170 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
20180 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
20190 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
201a0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
201b0 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
201c0 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
201d0 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
201e0 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
201f0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
20200 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
20210 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
20220 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
20230 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
20240 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
20250 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
20260 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
20270 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
20280 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
20290 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
202a0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
202b0 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
202c0 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
202d0 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
202e0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
202f0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
20300 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
20310 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
20320 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
20330 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
20340 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
20350 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
20360 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
20370 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
20380 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
20390 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
203a0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
203b0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
203c0 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
203d0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
203e0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
203f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20400 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
20410 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
20420 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
20430 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f  sqlite3.** KEYWO
20440 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72  RDS: {authorizer
20450 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a   callback}.**.**
20460 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
20470 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
20480 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20490 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
204a0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
204b0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
204c0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
204d0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
204e0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
204f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
20500 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
20510 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
20520 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
20530 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20540 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
20550 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
20560 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
20570 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
20580 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
20590 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c  epare16()], [sql
205a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
205b0 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71  2()],.** and [sq
205c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
205d0 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v3()].  ^At vari
205e0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
205f0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
20600 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
20610 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
20620 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
20630 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
20640 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
20650 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20660 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
20670 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
20680 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
20690 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
206a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
206b0 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
206c0 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
206d0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
206e0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
206f0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
20700 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
20710 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
20720 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
20730 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
20740 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
20750 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
20760 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
20770 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
20780 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
20790 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
207a0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
207b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
207c0 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
207d0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
207e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
207f0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
20800 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
20810 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
20820 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f  _prepare_v3()] o
20830 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
20840 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
20850 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
20860 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
20870 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
20880 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
20890 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
208a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
208b0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
208c0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
208d0 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
208e0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
208f0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20900 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
20910 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20920 5f 76 33 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v3()] or equiva
20930 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
20940 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
20950 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
20960 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
20970 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
20980 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
20990 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
209a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
209b0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
209c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
209d0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
209e0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
209f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20a00 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
20a10 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
20a20 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
20a30 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
20a40 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
20a50 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
20a60 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
20a70 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
20a80 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
20a90 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
20aa0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
20ab0 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
20ac0 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
20ad0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
20ae0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69   callback are ei
20af0 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ther NULL pointe
20b00 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69  rs or zero-termi
20b10 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  nated strings.**
20b20 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
20b30 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
20b40 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
20b50 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
20b60 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ed..** Applicati
20b70 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ons must always 
20b80 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65  be prepared to e
20b90 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20  ncounter a NULL 
20ba0 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a  pointer in any.*
20bb0 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74  * of the third t
20bc0 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68  hrough the sixth
20bd0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
20be0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
20bf0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
20c00 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
20c10 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
20c20 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
20c30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20c40 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
20c50 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
20c60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20c70 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
20c80 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
20c90 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
20ca0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
20cb0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
20cc0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
20cd0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
20ce0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
20cf0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
20d00 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
20d10 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
20d20 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
20d30 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
20d40 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
20d50 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
20d60 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
20d70 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20  table..** ^When 
20d80 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72  a table is refer
20d90 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45  enced by a [SELE
20da0 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  CT] but no colum
20db0 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20  n values are.** 
20dc0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74  extracted from t
20dd0 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65  hat table (for e
20de0 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72  xample in a quer
20df0 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43  y like.** "SELEC
20e00 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20  T count(*) FROM 
20e10 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b  tab") then the [
20e20 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74  SQLITE_READ] aut
20e30 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20e40 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  .** is invoked o
20e50 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62  nce for that tab
20e60 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e  le with a column
20e70 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e   name that is an
20e80 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
20e90 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
20ea0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
20eb0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
20ec0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20ed0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
20ee0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
20ef0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
20f00 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
20f10 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
20f20 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
20f30 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
20f40 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
20f50 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
20f60 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
20f70 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
20f80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20f90 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
20fa0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
20fb0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
20fc0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
20fd0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
20fe0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
20ff0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
21000 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
21010 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
21020 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
21030 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
21040 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
21050 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
21060 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
21070 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
21080 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
21090 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
210a0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
210b0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
210c0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
210d0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
210e0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
210f0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
21100 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
21110 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
21120 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
21130 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
21140 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
21150 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
21160 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
21170 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
21180 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
21190 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
211a0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
211b0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
211c0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
211d0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
211e0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
211f0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
21200 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
21210 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
21220 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
21230 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
21240 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
21250 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
21260 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
21270 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
21280 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
21290 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
212a0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
212b0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
212c0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
212d0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
212e0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
212f0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
21300 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
21310 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
21320 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
21330 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
21340 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
21350 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
21360 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
21370 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
21380 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
21390 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
213a0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
213b0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
213c0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
213d0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
213e0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
213f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
21400 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
21410 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
21420 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
21430 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
21440 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21450 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
21460 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21470 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
21480 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
21490 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 20 5b 73  are_v3()] and [s
214a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
214b0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
214c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
214d0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
214e0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
214f0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
21500 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
21510 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
21520 70 61 72 65 5f 76 33 28 29 5d 20 69 73 20 75 73  pare_v3()] is us
21530 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
21540 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
21550 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
21560 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
21570 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
21580 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
21590 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
215a0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
215b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
215c0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
215d0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
215e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
215f0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
21600 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
21610 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
21620 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
21630 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
21640 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
21650 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
21660 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21670 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
21680 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
21690 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
216a0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
216b0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
216c0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
216d0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
216e0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
216f0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
21700 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
21710 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
21720 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
21730 65 70 61 72 65 5f 76 33 28 29 20 74 6f 20 72 65  epare_v3() to re
21740 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
21750 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
21760 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
21770 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
21780 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
21790 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
217a0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
217b0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
217c0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
217d0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
217e0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
217f0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
21800 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
21810 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
21820 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
21830 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21840 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
21850 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
21860 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
21870 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
21880 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
21890 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
218a0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
218b0 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
218c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
218d0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
218e0 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
218f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
21900 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
21910 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
21920 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
21930 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
21940 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
21950 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
21960 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
21970 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
21980 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
21990 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
219a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
219b0 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
219c0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
219d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
219e0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
219f0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
21a00 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
21a10 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
21a20 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
21a30 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
21a40 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
21a50 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
21a60 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
21a70 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
21a80 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
21a90 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
21aa0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21ab0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
21ac0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
21ad0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
21ae0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
21af0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
21b00 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
21b10 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
21b20 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
21b30 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
21b40 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
21b50 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
21b60 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
21b70 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
21b80 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
21b90 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
21ba0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
21bb0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
21bc0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
21bd0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
21be0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
21bf0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
21c00 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
21c10 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
21c20 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
21c30 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
21c40 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
21c50 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
21c60 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
21c70 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
21c80 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
21c90 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
21ca0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
21cb0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
21cc0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
21cd0 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
21ce0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
21cf0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
21d00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21d10 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21d20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
21d30 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
21d40 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
21d50 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
21d60 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
21d70 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21d80 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
21d90 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
21da0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
21db0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
21dc0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
21dd0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
21de0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
21df0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
21e00 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
21e10 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
21e20 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
21e30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e50 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
21e60 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
21e70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
21e80 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21e90 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21ea0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
21eb0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21ec0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21ed0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21ee0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
21ef0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21f00 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21f10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21f20 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21f30 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
21f40 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
21f50 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
21f60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21f70 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21f80 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
21f90 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21fa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21fb0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21fc0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21fd0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
21fe0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
21ff0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22000 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22010 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22020 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
22030 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22040 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22050 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22060 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
22070 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
22080 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22090 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
220a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
220b0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
220c0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
220d0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
220e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
220f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22100 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
22110 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
22120 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22130 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22140 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22150 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
22160 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
22170 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22180 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
221a0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
221b0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
221c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
221d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
221e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
221f0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
22200 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
22210 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22220 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22240 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
22250 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
22260 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22270 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22280 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22290 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
222a0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
222b0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
222c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
222d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
222e0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
222f0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
22300 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
22310 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22320 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22330 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
22340 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
22350 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22360 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22370 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
22380 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
22390 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
223a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
223b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
223c0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
223d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
223e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
223f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22400 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22410 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
22420 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
22430 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
22440 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
22450 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
22460 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
22470 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
22480 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22490 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
224a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
224b0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
224c0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
224d0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
224e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
224f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22500 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
22510 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
22520 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
22530 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22540 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22550 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
22560 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
22570 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22580 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
22590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
225a0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
225b0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
225c0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
225d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
225e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
225f0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
22600 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
22610 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
22620 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22630 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22640 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
22650 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
22660 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
22670 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22690 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
226a0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
226b0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
226c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
226d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
226e0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
226f0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
22700 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22710 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22720 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22730 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
22740 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
22750 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
22760 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
22770 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22780 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
22790 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
227a0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
227b0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
227c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
227d0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
227e0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
227f0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
22800 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
22810 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
22820 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
22830 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
22840 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
22850 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
22860 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
22870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22880 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
22890 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
228a0 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
228b0 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
228c0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
228d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
228e0 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
228f0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
22900 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
22910 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
22920 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
22930 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22940 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
22950 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
22960 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
22970 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
22980 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
22990 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
229a0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
229b0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
229c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
229d0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
229e0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
229f0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
22a00 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
22a10 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
22a20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
22a30 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
22a40 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
22a50 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
22a60 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
22a70 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
22a80 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
22a90 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
22aa0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
22ab0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
22ac0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
22ad0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22ae0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
22af0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
22b00 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
22b10 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
22b20 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
22b30 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
22b40 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
22b50 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
22b60 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
22b70 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
22b80 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
22b90 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
22ba0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
22bb0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
22bc0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
22bd0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
22be0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
22bf0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
22c00 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
22c10 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
22c20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
22c30 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
22c40 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
22c50 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
22c60 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
22c70 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
22c80 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
22c90 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
22ca0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22cb0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
22cc0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
22cd0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
22ce0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
22cf0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
22d00 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
22d10 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
22d20 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
22d30 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
22d40 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
22d50 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
22d60 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
22d70 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
22d80 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
22d90 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
22da0 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
22db0 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
22dc0 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
22dd0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
22de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
22df0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
22e00 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
22e10 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
22e20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
22e30 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
22e40 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
22e50 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
22e60 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22e70 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
22e80 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
22e90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
22ea0 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
22eb0 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
22ec0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
22ed0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
22ee0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
22ef0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
22f00 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
22f10 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
22f20 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
22f30 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
22f40 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
22f50 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
22f60 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
22f70 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
22f80 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
22f90 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
22fa0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
22fb0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
22fc0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
22fd0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
22fe0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
22ff0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
23000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23010 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
23020 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
23030 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
23040 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
23050 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
23060 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
23070 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
23080 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
23090 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
230a0 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
230b0 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72  logic.  The thir
230c0 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
230d0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
230e0 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  v2()] is an OR-e
230f0 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
23100 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
23110 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
23120 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
23130 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
23140 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
23150 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
23160 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
23170 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
23180 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
23190 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
231a0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
231b0 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
231c0 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
231d0 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
231e0 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
231f0 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
23200 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
23210 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
23220 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
23230 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
23240 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
23250 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
23260 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
23270 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
23280 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
23290 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
232a0 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
232b0 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
232c0 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
232d0 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
232e0 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
232f0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
23300 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
23310 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
23320 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
23330 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
23340 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
23350 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
23360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23370 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
23380 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
23390 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
233a0 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
233b0 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
233c0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
233d0 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
233e0 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
233f0 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
23400 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
23410 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
23420 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23430 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
23440 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
23450 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
23460 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
23470 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
23480 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
23490 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
234a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
234b0 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
234c0 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
234d0 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
234e0 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
234f0 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
23500 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
23510 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
23520 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
23530 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
23540 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
23550 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
23560 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
23570 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
23580 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
23590 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
235a0 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
235b0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
235c0 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
235d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
235e0 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
235f0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
23600 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
23610 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
23620 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
23630 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
23640 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
23650 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
23660 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
23670 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
23680 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
23690 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
236a0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
236b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
236c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
236d0 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
236e0 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
236f0 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
23700 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
23710 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
23720 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
23730 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
23740 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
23750 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
23760 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
23770 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23780 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
23790 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
237a0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
237b0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
237c0 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
237d0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
237e0 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
237f0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
23800 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
23810 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
23820 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
23830 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
23840 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
23850 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
23860 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
23870 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23880 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23890 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
238a0 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
238b0 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
238c0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
238d0 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
238e0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
238f0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
23900 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
23910 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
23920 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ked when a datab
23930 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
23940 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
23950 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
23960 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23970 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23980 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
23990 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
239a0 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
239b0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
239c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
239d0 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
239e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
239f0 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
23a00 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
23a10 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
23a20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
23a30 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
23a40 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
23a50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23a60 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
23a70 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
23a80 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
23a90 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
23aa0 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
23ab0 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
23ac0 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
23ad0 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
23ae0 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
23af0 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
23b00 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
23b10 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
23b20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
23b30 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
23b40 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
23b50 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
23b60 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
23b70 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
23b80 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
23b90 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
23ba0 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
23bb0 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
23bc0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
23bd0 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
23be0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
23bf0 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
23c00 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23c10 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
23c20 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
23c30 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
23c40 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
23c50 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
23c60 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
23c70 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
23c80 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
23c90 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
23ca0 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
23cb0 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
23cc0 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
23cd0 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
23ce0 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
23cf0 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
23d00 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
23d10 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
23d20 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
23d30 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
23d40 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
23d50 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
23d60 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
23d70 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
23d80 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
23d90 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
23da0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
23db0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
23dc0 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
23dd0 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
23de0 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
23df0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
23e00 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
23e10 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
23e20 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
23e30 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
23e40 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
23e50 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
23e60 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
23e70 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
23e80 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
23e90 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
23ea0 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
23eb0 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
23ec0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23ed0 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
23ee0 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
23ef0 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
23f00 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
23f10 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
23f20 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
23f30 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
23f40 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
23f50 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
23f60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23f70 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
23f80 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
23f90 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a  d uMask,.  int(*
23fa0 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
23fb0 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
23fc0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
23fd0 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
23fe0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
23ff0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
24000 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
24010 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
24020 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
24030 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
24040 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
24050 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
24060 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
24070 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
24080 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
24090 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
240a0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
240b0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
240c0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
240d0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
240e0 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
240f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24100 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
24110 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
24120 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
24130 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
24140 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
24150 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
24160 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
24170 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
24180 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
24190 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
241a0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
241b0 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
241c0 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
241d0 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
241e0 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
241f0 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
24200 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
24210 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
24220 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
24230 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
24240 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
24250 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
24260 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
24270 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
24280 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
24290 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
242a0 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
242b0 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
242c0 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
242d0 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
242e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
242f0 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
24300 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24310 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
24320 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
24330 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
24340 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
24350 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
24360 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
24370 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
24380 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
24390 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
243a0 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
243b0 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
243c0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
243d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
243e0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
243f0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
24400 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
24410 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
24420 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
24430 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
24440 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
24450 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
24460 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
24470 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24480 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
24490 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
244a0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
244b0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
244c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
244d0 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
244e0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
244f0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
24500 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
24510 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
24520 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
24530 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
24540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
24550 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
24560 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
24570 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
24580 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
24590 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
245a0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
245b0 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
245c0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
245d0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
245e0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
245f0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
24600 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
24610 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
24620 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
24630 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
24640 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
24650 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
24660 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24670 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
24680 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
24690 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
246a0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
246b0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
246c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
246d0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
246e0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
246f0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
24700 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
24710 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
24720 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
24730 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
24740 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
24750 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
24760 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
24770 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
24780 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
24790 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
247a0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
247b0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
247c0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
247d0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
247e0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
247f0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
24800 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
24810 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
24820 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
24830 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24840 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
24850 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
24860 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
24870 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
24880 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
24890 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
248a0 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
248b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
248c0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
248d0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
248e0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
248f0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
24900 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
24910 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
24920 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
24930 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
24940 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
24950 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
24960 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
24970 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
24980 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
24990 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
249a0 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
249b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
249c0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
249d0 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
249e0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
249f0 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
24a00 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
24a10 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
24a20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
24a30 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
24a40 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
24a50 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
24a60 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
24a70 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
24a80 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
24a90 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
24aa0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
24ab0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
24ac0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
24ad0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
24ae0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
24af0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
24b00 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
24b10 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
24b20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24b30 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
24b40 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
24b50 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
24b60 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
24b70 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
24b80 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
24b90 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
24ba0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
24bb0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
24bc0 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
24bd0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
24be0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24bf0 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
24c00 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
24c10 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
24c20 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
24c30 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
24c40 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
24c50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
24c60 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
24c70 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
24c80 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
24c90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
24ca0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
24cb0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
24cc0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
24cd0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
24ce0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
24cf0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
24d00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
24d10 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
24d20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
24d30 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
24d40 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
24d50 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
24d60 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
24d70 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
24d80 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
24d90 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
24da0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24db0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24dc0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
24dd0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
24de0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
24df0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
24e00 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
24e10 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
24e20 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
24e30 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
24e40 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
24e50 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
24e60 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
24e70 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
24e80 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
24e90 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
24ea0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
24eb0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
24ec0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
24ed0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
24ee0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
24ef0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
24f00 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
24f10 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
24f20 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
24f30 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
24f40 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
24f50 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
24f60 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
24f70 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
24f80 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
24f90 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
24fa0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
24fb0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
24fc0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
24fd0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
24fe0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
24ff0 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
25000 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
25010 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
25020 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
25030 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
25040 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
25050 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
25060 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
25070 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
25080 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
25090 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
250a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
250b0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
250c0 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
250d0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
250e0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
250f0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
25100 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
25110 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
25120 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
25130 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
25140 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
25150 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
25160 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
25170 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25180 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
25190 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
251a0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
251b0 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
251c0 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
251d0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
251e0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
251f0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
25200 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
25210 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
25220 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
25230 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
25240 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
25250 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
25260 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
25270 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
25280 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
25290 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
252a0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
252b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
252c0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
252d0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
252e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
252f0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
25300 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
25310 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
25320 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
25330 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
25340 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
25350 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
25360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
25370 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
25380 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25390 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
253a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
253b0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
253c0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
253d0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
253e0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
253f0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
25400 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
25410 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
25420 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
25430 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
25440 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
25450 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
25460 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
25470 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
25480 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
25490 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
254a0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
254b0 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
254c0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
254d0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
254e0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
254f0 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
25500 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
25510 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
25520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25530 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
25540 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
25550 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
25560 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
25570 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
25580 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
25590 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
255a0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
255b0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
255c0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
255d0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
255e0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
255f0 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
25600 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
25610 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
25620 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
25630 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
25640 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
25650 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
25660 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
25670 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
25680 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
25690 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
256a0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
256b0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
256c0 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
256d0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
256e0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
256f0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
25700 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
25710 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25720 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
25730 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
25740 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
25750 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
25760 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
25770 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
25780 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
25790 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
257a0 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
257b0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
257c0 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
257d0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
257e0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
257f0 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
25800 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
25810 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
25820 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
25830 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
25840 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
25850 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
25860 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
25870 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25880 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
25890 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
258a0 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
258b0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
258c0 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
258d0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
258e0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
258f0 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
25900 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
25910 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
25920 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
25930 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
25940 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
25950 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
25960 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
25970 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
25980 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
25990 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
259a0 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
259b0 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
259c0 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
259d0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
259e0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
259f0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
25a00 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
25a10 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
25a20 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
25a30 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
25a40 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
25a50 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
25a60 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
25a70 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
25a80 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
25a90 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
25aa0 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
25ab0 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
25ac0 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
25ad0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
25ae0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
25af0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
25b00 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
25b10 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
25b20 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
25b30 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
25b40 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
25b50 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
25b60 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
25b70 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
25b80 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
25b90 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
25ba0 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
25bb0 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
25bc0 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
25bd0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
25be0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
25bf0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
25c00 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
25c10 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
25c20 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
25c30 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
25c40 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
25c50 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
25c60 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
25c70 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
25c80 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
25c90 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
25ca0 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
25cb0 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
25cc0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
25cd0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
25ce0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
25cf0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
25d00 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
25d10 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
25d20 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
25d30 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
25d40 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
25d50 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
25d60 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
25d70 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
25d80 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
25d90 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
25da0 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
25db0 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
25dc0 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
25dd0 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
25de0 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
25df0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
25e00 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
25e10 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
25e20 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
25e30 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
25e40 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
25e50 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
25e60 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
25e70 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
25e80 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
25e90 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
25ea0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
25eb0 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
25ec0 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
25ed0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
25ee0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
25ef0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
25f00 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
25f10 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
25f20 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
25f30 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
25f40 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
25f50 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
25f60 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
25f70 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
25f80 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
25f90 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
25fa0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
25fb0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
25fc0 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
25fd0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
25fe0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
25ff0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
26000 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
26010 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
26020 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
26030 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
26040 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
26050 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
26060 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
26070 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
26080 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
26090 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
260a0 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
260b0 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
260c0 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
260d0 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
260e0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
260f0 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
26100 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
26110 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
26120 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
26130 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
26140 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
26150 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
26160 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
26170 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
26180 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
26190 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
261a0 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
261b0 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
261c0 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
261d0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
261e0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
261f0 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
26200 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
26210 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
26220 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
26230 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
26240 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
26250 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
26260 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
26270 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
26280 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
26290 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
262a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
262b0 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
262c0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
262d0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
262e0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
262f0 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
26300 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
26310 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
26320 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
26330 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
26340 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
26350 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
26360 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
26370 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
26380 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
26390 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
263a0 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
263b0 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
263c0 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
263d0 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
263e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
263f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
26400 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
26410 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
26420 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
26430 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
26440 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
26450 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
26460 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
26470 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
26480 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
26490 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
264a0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
264b0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
264c0 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
264d0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
264e0 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
264f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
26500 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
26510 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
26520 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
26530 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
26540 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
26550 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
26560 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
26570 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
26580 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
26590 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
265a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
265b0 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
265c0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
265d0 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
265e0 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
265f0 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
26600 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
26610 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
26620 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
26630 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
26640 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
26650 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
26660 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
26670 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
26680 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
26690 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
266a0 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
266b0 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
266c0 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
266d0 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
266e0 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
266f0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
26700 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
26710 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
26720 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
26730 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
26740 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
26750 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
26760 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
26770 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
26780 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
26790 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
267a0 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
267b0 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
267c0 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
267d0 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
267e0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
267f0 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
26800 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
26810 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
26820 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
26830 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
26840 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
26850 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
26860 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
26870 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
26880 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
26890 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
268a0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
268b0 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
268c0 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
268d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
268e0 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
268f0 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
26900 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
26910 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26920 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
26930 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
26940 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
26950 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
26960 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
26970 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
26980 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
26990 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
269a0 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
269b0 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
269c0 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
269d0 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
269e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
269f0 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
26a00 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
26a10 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
26a20 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
26a30 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
26a40 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
26a50 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
26a60 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
26a70 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
26a80 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
26a90 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
26aa0 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
26ab0 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
26ac0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
26ad0 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
26ae0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
26af0 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
26b00 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
26b10 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
26b20 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
26b30 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
26b40 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
26b50 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
26b60 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
26b70 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
26b80 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
26b90 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
26ba0 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
26bb0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
26bc0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
26bd0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
26be0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
26bf0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
26c00 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
26c10 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
26c20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
26c30 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
26c40 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
26c50 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
26c60 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
26c70 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
26c80 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
26c90 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
26ca0 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
26cb0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
26cc0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
26cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
26ce0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
26cf0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
26d00 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
26d10 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26d20 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26d30 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
26d40 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
26d50 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
26d60 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
26d70 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
26d80 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26d90 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
26da0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
26db0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
26dc0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
26dd0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
26de0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
26df0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
26e00 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
26e10 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
26e20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
26e30 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
26e40 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
26e50 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
26e60 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
26e70 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
26e80 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
26e90 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
26ea0 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
26eb0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
26ec0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
26ed0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
26ee0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
26ef0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
26f00 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
26f10 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
26f20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
26f30 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
26f40 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
26f50 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
26f60 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
26f70 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
26f80 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
26f90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
26fa0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
26fb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26fc0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
26fd0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
26fe0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26ff0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
27000 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
27010 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
27020 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
27030 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
27040 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
27050 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
27060 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
27070 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
27080 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
27090 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
270a0 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
270b0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
270c0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
270d0 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
270e0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
270f0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
27100 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
27110 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
27120 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
27130 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
27140 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
27150 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
27160 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
27170 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
27180 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
27190 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
271a0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
271b0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
271c0 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
271d0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
271e0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
271f0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
27200 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
27210 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
27220 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
27230 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
27240 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
27250 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
27260 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
27270 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
27280 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
27290 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
272a0 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
272b0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
272c0 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
272d0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
272e0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
272f0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
27300 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
27310 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
27320 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
27330 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
27340 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
27350 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
27360 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
27370 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
27380 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
27390 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
273a0 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
273b0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
273c0 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
273d0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
273e0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
273f0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
27400 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
27410 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
27420 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
27430 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
27440 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
27450 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
27460 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
27470 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
27480 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
27490 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
274a0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
274b0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
274c0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
274d0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
274e0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
274f0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
27500 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
27510 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
27520 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
27530 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
27540 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
27550 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
27560 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
27570 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
27580 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
27590 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
275a0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
275b0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
275c0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
275d0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
275e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
275f0 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
27600 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
27610 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
27620 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
27630 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
27640 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
27650 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
27660 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
27670 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
27680 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
27690 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
276a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
276b0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
276c0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
276d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
276e0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
276f0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
27700 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
27710 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
27720 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
27730 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
27740 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
27750 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
27760 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27770 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
27780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27790 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
277a0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
277b0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
277c0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
277d0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
277e0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
277f0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
27800 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
27810 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
27820 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
27830 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
27840 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
27850 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
27860 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
27870 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
27880 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
27890 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
278a0 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
278b0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
278c0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
278d0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
278e0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
278f0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
27900 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
27910 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
27920 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
27930 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
27940 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
27950 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
27960 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
27970 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
27980 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
27990 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
279a0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
279b0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
279c0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
279d0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
279e0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
279f0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
27a00 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
27a10 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
27a20 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
27a30 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
27a40 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
27a50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
27a60 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
27a70 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
27a80 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27a90 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
27aa0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
27ab0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
27ac0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
27ad0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
27ae0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
27af0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
27b00 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
27b10 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
27b20 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
27b30 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
27b40 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
27b50 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
27b60 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
27b70 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
27b80 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
27b90 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
27ba0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27bb0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
27bc0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
27bd0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
27be0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
27bf0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
27c00 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
27c10 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
27c20 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
27c30 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
27c40 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27c50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
27c60 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
27c70 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
27c80 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
27c90 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
27ca0 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
27cb0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
27cc0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
27cd0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
27ce0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
27cf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27d00 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27d10 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
27d20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
27d30 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
27d40 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
27d50 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
27d60 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
27d70 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
27d80 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
27d90 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
27da0 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
27db0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
27dc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
27dd0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
27de0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
27df0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
27e00 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
27e10 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
27e20 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27e30 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
27e40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27e50 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
27e60 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
27e70 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
27e80 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
27e90 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
27ea0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
27eb0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
27ec0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
27ed0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
27ee0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
27ef0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
27f00 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
27f10 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
27f20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
27f30 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
27f40 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
27f50 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
27f60 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
27f70 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
27f80 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
27f90 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
27fa0 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
27fb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
27fc0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
27fd0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
27fe0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
27ff0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
28000 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
28010 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
28020 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
28030 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
28040 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
28050 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
28060 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
28070 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28080 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
28090 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
280a0 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
280b0 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
280c0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
280d0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
280e0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
280f0 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
28100 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
28110 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
28120 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
28130 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
28140 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
28150 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
28160 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
28170 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
28180 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28190 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  3.**.** ^If the 
281a0 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69  most recent sqli
281b0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
281c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a  ssociated with .
281d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
281e0 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65  nection] D faile
281f0 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  d, then the sqli
28200 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69  te3_errcode(D) i
28210 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
28220 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
28230 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
28240 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
28250 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74  t code] for that
28260 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a  .** API call..**
28270 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
28280 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73  ent API call was
28290 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20   successful,.** 
282a0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
282b0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
282c0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
282d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54  undefined..** ^T
282e0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
282f0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
28300 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
28310 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
28320 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
28330 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
28340 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
28350 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
28360 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
28370 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
28380 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
28390 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
283a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
283b0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
283c0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
283d0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
283e0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
283f0 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
28400 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
28410 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
28420 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
28430 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
28440 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
28450 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
28460 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
28470 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
28480 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
28490 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
284a0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
284b0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
284c0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
284d0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
284e0 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
284f0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
28500 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
28510 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
28520 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28530 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
28540 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
28550 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
28560 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
28570 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
28580 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
28590 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
285a0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
285b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
285c0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
285d0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
285e0 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
285f0 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
28600 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
28610 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
28620 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
28630 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
28640 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
28650 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
28660 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
28670 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
28680 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
28690 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
286a0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
286b0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
286c0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
286d0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
286e0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
286f0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
28700 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
28710 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
28720 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
28730 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
28740 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
28750 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
28760 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
28770 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
28780 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
28790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
287a0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
287b0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
287c0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
287d0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
287e0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
287f0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
28800 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
28810 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
28820 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
28830 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
28840 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
28850 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
28860 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
28870 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
28880 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
28890 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
288a0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
288b0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
288c0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
288d0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
288e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
288f0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
28900 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
28910 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
28920 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
28930 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28940 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
28950 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
28960 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
28970 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
28980 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
28990 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
289a0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
289b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
289c0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
289d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
289e0 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
289f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28a00 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
28a10 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
28a20 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
28a30 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
28a40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28a50 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
28a60 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
28a70 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
28a80 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
28a90 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
28aa0 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
28ab0 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
28ac0 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
28ad0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
28ae0 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
28af0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
28b00 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
28b10 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
28b20 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
28b30 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
28b40 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
28b50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28b60 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
28b70 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
28b80 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
28b90 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
28ba0 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
28bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28bc0 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
28bd0 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
28be0 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
28bf0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
28c00 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
28c10 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
28c20 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
28c30 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
28c40 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28c50 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
28c60 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
28c70 72 65 5f 76 33 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v3()]..** <li
28c80 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
28c90 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
28ca0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
28cb0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
28cc0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
28cd0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
28ce0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
28cf0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
28d00 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
28d10 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
28d20 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28d30 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
28d40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
28d50 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
28d60 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
28d70 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
28d80 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
28d90 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
28da0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
28db0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
28dc0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
28dd0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28de0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
28df0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
28e00 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
28e10 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
28e20 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
28e30 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
28e40 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
28e50 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
28e60 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
28e70 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
28e80 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
28e90 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
28ea0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
28eb0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
28ec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28ed0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
28ee0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
28ef0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
28f00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
28f10 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
28f20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
28f30 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
28f40 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
28f50 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
28f60 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
28f70 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
28f80 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
28f90 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
28fa0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
28fb0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
28fc0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
28fd0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
28fe0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
28ff0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
29000 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
29010 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
29020 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
29030 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
29040 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
29050 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
29060 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
29070 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
29080 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
29090 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
290a0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
290b0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
290c0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
290d0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
290e0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
290f0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
29100 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
29110 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
29120 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
29130 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
29140 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
29150 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
29160 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
29170 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
29180 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
29190 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
291a0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
291b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
291c0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
291d0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
291e0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
291f0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
29200 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
29210 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
29220 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
29230 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
29240 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
29250 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
29260 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
29270 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
29280 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
29290 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
292a0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
292b0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
292c0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
292d0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
292e0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
292f0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
29300 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
29310 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
29320 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
29330 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
29340 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
29350 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
29360 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
29370 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
29380 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
29390 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
293a0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
293b0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
293c0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
293d0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
293e0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
293f0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
29400 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
29410 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
29420 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
29430 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
29440 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
29450 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
29460 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
29470 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
29480 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
29490 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
294a0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
294b0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
294c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
294d0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
294e0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
294f0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
29500 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
29510 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
29520 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
29530 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
29540 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
29550 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
29560 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
29570 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
29580 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
29590 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
295a0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
295b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
295c0 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
295d0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
295e0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
295f0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
29600 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
29610 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
29620 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
29630 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
29640 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
29650 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
29660 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
29670 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
29680 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
29690 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
296a0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
296b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
296c0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
296d0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
296e0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
296f0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
29700 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
29710 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
29720 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
29730 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
29740 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
29750 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
29760 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
29770 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
29780 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29790 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
297a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
297b0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
297c0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
297d0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
297e0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
297f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
29800 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
29810 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
29820 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
29830 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29840 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
29850 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
29860 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
29870 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29880 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
29890 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
298a0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
298b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
298c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
298d0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
298e0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
298f0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
29900 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
29910 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29920 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
29930 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
29940 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
29950 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
29960 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29970 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
29980 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
29990 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
299a0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
299b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
299c0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
299d0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
299e0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
299f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29a00 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
29a10 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
29a20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
29a30 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
29a40 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29a50 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
29a60 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
29a70 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
29a80 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
29a90 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29aa0 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
29ab0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
29ac0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
29ad0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29ae0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
29af0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
29b00 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
29b10 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
29b20 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
29b30 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c  tement.  If [sql
29b40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
29b50 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75  )] or.** the equ
29b60 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f  ivalent tries to
29b70 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20   allocate space 
29b80 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  for more than th
29b90 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a  is many opcodes.
29ba0 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70  ** in a single p
29bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29bc0 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d  t, an SQLITE_NOM
29bd0 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  EM error is retu
29be0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
29bf0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29c00 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
29c10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29c20 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
29c30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29c40 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29c50 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
29c60 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
29c70 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29c80 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
29c90 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29ca0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
29cb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29cc0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29cd0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
29ce0 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
29cf0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
29d00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
29d10 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
29d20 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
29d30 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
29d40 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
29d50 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29d60 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
29d70 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
29d80 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
29d90 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
29da0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
29db0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29dc0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
29dd0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
29de0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29df0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
29e00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29e10 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
29e20 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
29e30 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
29e40 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
29e50 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29e60 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
29e70 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29e80 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
29e90 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29ea0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
29eb0 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
29ec0 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
29ed0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29ee0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
29ef0 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
29f00 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
29f10 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
29f20 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29f30 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
29f40 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
29f50 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
29f60 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
29f70 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
29f80 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
29f90 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
29fa0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
29fb0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
29fc0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
29fd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
29fe0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
29ff0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2a000 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2a010 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
2a020 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
2a030 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a040 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
2a050 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
2a060 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a070 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2a080 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
2a090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a0a0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
2a0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
2a0c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a0d0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2a0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
2a0f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a100 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
2a110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
2a120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a130 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2a140 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
2a150 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
2a160 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2a170 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
2a180 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
2a190 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2a1a0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2a1b0 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
2a1c0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2a1d0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
2a1e0 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
2a1f0 33 52 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c  3REF: Prepare Fl
2a200 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
2a210 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
2a220 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73 20 74   various flags t
2a230 68 61 74 20 63 61 6e 20 62 65 20 70 61 73 73 65  hat can be passe
2a240 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46  d into.** "prepF
2a250 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65 72 20  lags" parameter 
2a260 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2a270 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 61 6e  prepare_v3()] an
2a280 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  d.** [sqlite3_pr
2a290 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e  epare16_v3()] in
2a2a0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  terfaces..**.** 
2a2b0 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20 62 65  New flags may be
2a2c0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
2a2d0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
2a2e0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ite..**.** <dl>.
2a2f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50  ** [[SQLITE_PREP
2a300 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d  ARE_PERSISTENT]]
2a310 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52   ^(<dt>SQLITE_PR
2a320 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2a330 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a340 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2a350 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61 67 20  PERSISTENT flag 
2a360 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
2a370 70 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a  prepare_v3()].**
2a380 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2a390 65 70 61 72 65 31 36 5f 76 33 28 29 5d 0a 2a 2a  epare16_v3()].**
2a3a0 20 74 6f 20 6f 70 74 69 6d 69 7a 65 20 74 68 65   to optimize the
2a3b0 20 72 65 73 75 6c 74 69 6e 67 20 70 72 65 70 61   resulting prepa
2a3c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  red statement to
2a3d0 20 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72   be retained for
2a3e0 20 61 20 0a 2a 2a 20 72 65 6c 61 74 69 76 65 6c   a .** relativel
2a3f0 79 20 6c 6f 6e 67 20 61 6d 6f 75 6e 74 20 6f 66  y long amount of
2a400 20 74 69 6d 65 2e 29 5e 20 20 5e 57 69 74 68 6f   time.)^  ^Witho
2a410 75 74 20 74 68 69 73 20 66 6c 61 67 2c 0a 2a 2a  ut this flag,.**
2a420 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a430 65 5f 76 33 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v3()] and [sql
2a440 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a450 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61 74  3()] assume that
2a460 0a 2a 2a 20 74 68 65 20 70 72 65 70 61 72 65 64  .** the prepared
2a470 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2a480 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63  be used just onc
2a490 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66  e or at most a f
2a4a0 65 77 20 74 69 6d 65 73 0a 2a 2a 20 61 6e 64 20  ew times.** and 
2a4b0 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75  then destroyed u
2a4c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2a4d0 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69  nalize()] relati
2a4e0 76 65 6c 79 20 73 6f 6f 6e 2e 0a 2a 2a 20 3c 2f  vely soon..** </
2a4f0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
2a500 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2a510 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20  RSISTENT        
2a520 20 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a        0x01../*.*
2a530 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
2a540 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
2a550 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
2a560 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
2a570 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20  nt compiler}.** 
2a580 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
2a590 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
2a5a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2a5b0 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
2a5c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2a5d0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
2a5e0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
2a5f0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
2a600 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
2a610 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2a620 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72  s.  Or, in other
2a630 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f   words, these ro
2a640 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f  utines.** are co
2a650 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74  nstructors for t
2a660 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2a670 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
2a680 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72  **.** The prefer
2a690 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75  red routine to u
2a6a0 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70  se is [sqlite3_p
2a6b0 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54  repare_v2()].  T
2a6c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
2a6d0 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66  repare()] interf
2a6e0 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e  ace is legacy an
2a6f0 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  d should be avoi
2a700 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ded..** [sqlite3
2a710 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68  _prepare_v3()] h
2a720 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 65  as an extra "pre
2a730 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74  pFlags" option t
2a740 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66  hat is used.** f
2a750 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f  or special purpo
2a760 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ses..**.** The u
2a770 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20  se of the UTF-8 
2a780 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 72  interfaces is pr
2a790 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69  eferred, as SQLi
2a7a0 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  te currently.** 
2a7b0 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67  does all parsing
2a7c0 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54   using UTF-8.  T
2a7d0 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66  he UTF-16 interf
2a7e0 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
2a7f0 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e  d.** as a conven
2a800 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d  ience.  The UTF-
2a810 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  16 interfaces wo
2a820 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67  rk by converting
2a830 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65   the.** input te
2a840 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74  xt into UTF-8, t
2a850 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hen invoking the
2a860 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55   corresponding U
2a870 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a  TF-8 interface..
2a880 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2a890 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
2a8a0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
2a8b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
2a8c0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
2a8d0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
2a8e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a8f0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2a900 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
2a910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
2a920 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
2a930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a940 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2a950 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
2a960 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2a970 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
2a980 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
2a990 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
2a9a0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
2a9b0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
2a9c0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
2a9d0 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c  3_prepare(), sql
2a9e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a9f0 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2aa00 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a  3_prepare_v3().*
2aa10 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
2aa20 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
2aa30 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c  te3_prepare16(),
2aa40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2aa50 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2aa60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2aa70 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 31  6_v3() use UTF-1
2aa80 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
2aa90 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
2aaa0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2aab0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
2aac0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
2aad0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2aae0 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
2aaf0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
2ab00 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
2ab10 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
2ab20 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
2ab30 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
2ab40 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
2ab50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
2ab60 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
2ab70 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
2ab80 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
2ab90 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
2aba0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
2abb0 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
2abc0 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
2abd0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
2abe0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
2abf0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
2ac00 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2ac10 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2ac20 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
2ac30 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
2ac40 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
2ac50 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
2ac60 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
2ac70 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
2ac80 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2ac90 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
2aca0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
2acb0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
2acc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2acd0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
2ace0 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
2acf0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
2ad00 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
2ad10 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
2ad20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ad30 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
2ad40 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
2ad50 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
2ad60 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2ad70 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
2ad80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ad90 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
2ada0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
2adb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2adc0 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
2add0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
2ade0 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
2adf0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
2ae00 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
2ae10 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
2ae20 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
2ae30 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
2ae40 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
2ae50 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
2ae60 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
2ae70 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
2ae80 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
2ae90 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
2aea0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
2aeb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
2aec0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2aed0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
2aee0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2aef0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
2af00 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
2af10 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
2af20 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
2af30 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
2af40 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
2af50 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
2af60 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
2af70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2af80 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2af90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2afa0 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74  pare_v2(), sqlit
2afb0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c  e3_prepare_v3(),
2afc0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2afd0 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2afe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2aff0 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 65  6_v3() interface
2b000 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65  s are recommende
2b010 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
2b020 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f  ograms..** The o
2b030 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2b040 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  (sqlite3_prepare
2b050 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
2b060 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61  repare16()).** a
2b070 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
2b080 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2b090 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
2b0a0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
2b0b0 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
2b0c0 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  e "vX" interface
2b0d0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
2b0e0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
2b0f0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
2b100 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2b110 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
2b120 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2b130 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2b140 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
2b150 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
2b160 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
2b170 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
2b180 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
2b190 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
2b1a0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
2b1b0 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
2b1c0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
2b1d0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
2b1e0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
2b1f0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
2b200 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
2b210 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2b220 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
2b230 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
2b240 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
2b250 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
2b260 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
2b270 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
2b280 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
2b290 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
2b2a0 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
2b2b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
2b2c0 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
2b2d0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
2b2e0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2b2f0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
2b300 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
2b310 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2b320 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
2b330 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
2b340 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
2b350 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2b360 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
2b370 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
2b380 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
2b390 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
2b3a0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
2b3b0 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
2b3c0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
2b3d0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
2b3e0 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
2b3f0 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
2b400 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
2b410 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
2b420 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
2b430 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
2b440 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
2b450 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
2b460 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
2b470 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
2b480 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
2b490 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
2b4a0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
2b4b0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
2b4c0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2b4d0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2b4e0 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
2b4f0 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
2b500 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
2b510 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
2b520 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
2b530 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
2b540 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2b550 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
2b560 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
2b570 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
2b580 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2b590 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
2b5a0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
2b5b0 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
2b5c0 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
2b5d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b5e0 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
2b5f0 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
2b600 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
2b610 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
2b620 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
2b630 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
2b640 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2b650 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
2b660 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
2b670 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2b680 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
2b690 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
2b6a0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
2b6b0 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
2b6c0 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
2b6d0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
2b6e0 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
2b6f0 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
2b700 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
2b710 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
2b720 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
2b730 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
2b740 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
2b750 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
2b760 69 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c  i>.**.** <p>^sql
2b770 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2b780 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20 73  ) differs from s
2b790 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b7a0 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69  2() only in havi
2b7b0 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 20  ng.** the extra 
2b7c0 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65  prepFlags parame
2b7d0 74 65 72 2c 20 77 68 69 63 68 20 69 73 20 61 20  ter, which is a 
2b7e0 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69 73  bit array consis
2b7f0 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a  ting of zero or.
2b800 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
2b810 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2b820 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 45  ERSISTENT|SQLITE
2b830 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67  _PREPARE_*] flag
2b840 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  s.  ^The.** sqli
2b850 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2b860 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
2b870 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
2b880 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
2b890 70 72 65 70 61 72 65 5f 76 33 28 29 20 77 69 74  prepare_v3() wit
2b8a0 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c 61  h a zero prepFla
2b8b0 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  gs parameter..**
2b8c0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
2b8d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
2b8e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2b8f0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2b900 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2b910 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2b920 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2b930 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2b940 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2b950 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2b960 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2b970 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2b980 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2b990 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2b9a0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2b9b0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2b9c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2b9d0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2b9e0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2b9f0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2ba00 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2ba10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2ba20 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2ba30 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2ba40 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2ba50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2ba60 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2ba70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2ba80 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2ba90 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2baa0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2bab0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2bac0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2bad0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2bae0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2baf0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2bb00 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2bb10 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2bb20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2bb30 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2bb40 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2bb50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2bb60 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c  repare_v3(.  sql
2bb70 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2bb80 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2bb90 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2bba0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2bbb0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2bbc0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2bbd0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2bbe0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2bbf0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2bc00 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2bc10 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67  ytes. */.  unsig
2bc20 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67  ned int prepFlag
2bc30 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f  s, /* Zero or mo
2bc40 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  re SQLITE_PREPAR
2bc50 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71  E_ flags */.  sq
2bc60 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2bc70 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2bc80 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2bc90 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2bca0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2bcb0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2bcc0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2bcd0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2bce0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bcf0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2bd00 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2bd10 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2bd20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2bd30 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2bd40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2bd50 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2bd60 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2bd70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2bd80 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2bd90 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2bda0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2bdb0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2bdc0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2bdd0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2bde0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2bdf0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2be00 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2be10 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2be20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2be30 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2be40 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2be50 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2be60 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2be70 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2be80 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2be90 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2bea0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2beb0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2bec0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2bed0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2bee0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2bef0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2bf00 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2bf10 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2bf20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2bf30 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2bf40 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2bf50 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2bf60 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2bf70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2bf80 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2bf90 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2bfa0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2bfb0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2bfc0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2bfd0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2bfe0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2bff0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2c000 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c010 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2c020 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2c030 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69   */.  unsigned i
2c040 6e 74 20 70 72 65 70 46 61 6c 67 73 2c 20 2f 2a  nt prepFalgs, /*
2c050 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51   Zero or more SQ
2c060 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c  LITE_PREPARE_ fl
2c070 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  ags */.  sqlite3
2c080 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2c090 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2c0a0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2c0b0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2c0c0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2c0d0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2c0e0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2c0f0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2c100 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2c110 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2c120 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c130 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c140 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2c150 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2c160 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c170 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2c180 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2c190 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2c1a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c1b0 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2c1c0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b  .** created by [
2c1d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c1e0 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2c1f0 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a  prepare_v3()],.*
2c200 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c210 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
2c220 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c230 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  6_v3()]..** ^The
2c240 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2c250 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2c260 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2c270 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2c280 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2c290 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78  ning the SQL tex
2c2a0 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74  t of prepared st
2c2b0 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a  atement P with.*
2c2c0 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  * [bound paramet
2c2d0 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a  ers] expanded..*
2c2e0 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2c2f0 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65  le, if a prepare
2c300 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
2c310 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
2c320 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45   SQL.** text "SE
2c330 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2c340 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72  and if parameter
2c350 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74   $abc is bound t
2c360 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a  o integer 2345.*
2c370 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * and parameter 
2c380 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c  :xyz is unbound,
2c390 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71   then sqlite3_sq
2c3a0 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  l() will return.
2c3b0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
2c3c0 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20  string, "SELECT 
2c3d0 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73  $abc,:xyz" but s
2c3e0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2c3f0 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  sql().** will re
2c400 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34  turn "SELECT 234
2c410 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a  5,NULL".)^.**.**
2c420 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2c430 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74  panded_sql() int
2c440 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
2c450 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
2c460 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  ent memory.** is
2c470 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f   available to ho
2c480 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f  ld the result, o
2c490 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20  r if the result 
2c4a0 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
2c4b0 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  .** the maximum 
2c4c0 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65  string length de
2c4d0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2c4e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2c4f0 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  NGTH]..**.** ^Th
2c500 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
2c510 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
2c520 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2c530 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20  limits the size 
2c540 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61  of.** bound para
2c550 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73  meter expansions
2c560 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
2c570 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70  OMIT_TRACE] comp
2c580 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
2c590 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65  on causes sqlite
2c5a0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2c5b0 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72   to always retur
2c5c0 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n NULL..**.** ^T
2c5d0 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2c5e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71  ed by sqlite3_sq
2c5f0 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20  l(P) is managed 
2c600 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73  by SQLite and is
2c610 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
2c620 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65  y freed when the
2c630 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2c640 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2c650 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67  ..** ^The string
2c660 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2c670 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2c680 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68  l(P), on the oth
2c690 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f  er hand,.** is o
2c6a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2c6b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2c6c0 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65  and must be free
2c6d0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2c6e0 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e  ion.** by passin
2c6f0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
2c700 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  _free()]..*/.con
2c710 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2c720 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2c730 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20  t *pStmt);.char 
2c740 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  *sqlite3_expande
2c750 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  d_sql(sqlite3_st
2c760 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2c770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2c780 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
2c790 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
2c7a0 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
2c7b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c7c0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2c7d0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2c7e0 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
2c7f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2c800 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
2c810 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
2c820 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c830 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
2c840 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
2c850 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
2c860 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2c870 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
2c880 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
2c890 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2c8a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
2c8b0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
2c8c0 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
2c8d0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
2c8e0 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
2c8f0 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
2c900 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2c910 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
2c920 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
2c930 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
2c940 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
2c950 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
2c960 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
2c970 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
2c980 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
2c990 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2c9a0 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
2c9b0 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
2c9c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2c9d0 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
2c9e0 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
2c9f0 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
2ca00 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
2ca10 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
2ca20 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
2ca30 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
2ca40 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2ca50 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
2ca60 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
2ca70 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2ca80 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
2ca90 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
2caa0 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
2cab0 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
2cac0 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
2cad0 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
2cae0 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
2caf0 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
2cb00 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
2cb10 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2cb20 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2cb30 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
2cb40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
2cb50 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
2cb60 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
2cb70 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
2cb80 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
2cb90 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
2cba0 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
2cbb0 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
2cbc0 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
2cbd0 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
2cbe0 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
2cbf0 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
2cc00 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
2cc10 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2cc20 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2cc30 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
2cc40 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
2cc50 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
2cc60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
2cc70 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2cc80 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
2cc90 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
2cca0 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
2ccb0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2ccc0 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
2ccd0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2cce0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2ccf0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2cd00 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45  rns true for [BE
2cd10 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42  GIN] since.** [B
2cd20 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74  EGIN] merely set
2cd30 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73  s internal flags
2cd40 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e  , but the [BEGIN
2cd50 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45  |BEGIN IMMEDIATE
2cd60 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c  ] and.** [BEGIN|
2cd70 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d  BEGIN EXCLUSIVE]
2cd80 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75   commands do tou
2cd90 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
2cda0 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65  and so.** sqlite
2cdb0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2cdc0 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  ) returns false 
2cdd0 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e  for those comman
2cde0 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
2cdf0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2ce00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2ce10 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ce20 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2ce30 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
2ce40 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
2ce50 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48  en Reset.** METH
2ce60 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ce70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ce80 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2ce90 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cea0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2ceb0 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
2cec0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ced0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
2cee0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
2cef0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
2cf00 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
2cf10 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72  ut has neither r
2cf20 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
2cf30 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53   (returned.** [S
2cf40 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d  QLITE_DONE] from
2cf50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2cf60 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20  )]) nor.** been 
2cf70 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
2cf80 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
2cf90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2cfa0 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
2cfb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2cfc0 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
2cfd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
2cfe0 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
2cff0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2d000 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
2d010 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
2d020 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d030 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
2d040 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2d050 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2d060 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
2d070 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
2d080 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2d090 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
2d0a0 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
2d0b0 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
2d0c0 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
2d0d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d0e0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2d0f0 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
2d100 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2d110 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
2d120 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
2d130 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
2d140 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
2d150 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
2d160 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
2d170 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
2d180 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
2d190 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
2d1a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
2d1b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2d1c0 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
2d1d0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2d1e0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
2d1f0 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
2d200 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
2d210 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
2d220 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d230 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
2d240 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
2d250 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
2d260 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
2d270 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
2d280 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
2d290 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2d2a0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
2d2b0 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
2d2c0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2d2d0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
2d2e0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
2d2f0 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
2d300 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
2d310 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
2d320 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
2d330 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2d340 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
2d350 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
2d360 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
2d370 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
2d380 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
2d390 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
2d3a0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
2d3b0 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
2d3c0 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
2d3d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2d3e0 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
2d3f0 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
2d400 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
2d410 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
2d420 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d430 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
2d440 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
2d450 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
2d460 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
2d470 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
2d480 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
2d490 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
2d4a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2d4b0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
2d4c0 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69  3_value_dup()] i
2d4d0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2d4e0 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63  used to construc
2d4f0 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74  t a new .** prot
2d500 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d510 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72  lue from an unpr
2d520 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d530 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
2d540 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
2d550 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
2d560 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
2d570 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
2d580 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
2d590 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
2d5a0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
2d5b0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
2d5c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2d5d0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
2d5e0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
2d5f0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2d600 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2d610 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
2d620 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
2d630 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
2d640 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
2d650 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
2d660 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
2d670 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
2d680 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
2d690 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
2d6a0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
2d6b0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
2d6c0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
2d6d0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
2d6e0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
2d6f0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
2d700 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
2d710 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
2d720 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
2d730 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
2d740 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2d750 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
2d760 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
2d770 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
2d780 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
2d790 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
2d7a0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
2d7b0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2d7c0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
2d7d0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
2d7e0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
2d7f0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
2d800 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
2d810 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2d820 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
2d830 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
2d840 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
2d850 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
2d860 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
2d870 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
2d880 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
2d890 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
2d8a0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
2d8b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2d8c0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
2d8d0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
2d8e0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2d8f0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2d900 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2d910 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2d920 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
2d930 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
2d940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2d950 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
2d960 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
2d970 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2d980 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2d990 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2d9a0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2d9b0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
2d9c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2d9d0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
2d9e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
2d9f0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
2da00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2da10 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
2da20 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2da30 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
2da40 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2da50 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2da60 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2da70 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2da80 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2da90 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2daa0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2dab0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2dac0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2dad0 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2dae0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2daf0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2db00 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2db10 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2db20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2db30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2db40 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2db50 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2db60 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2db70 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2db80 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2db90 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2dba0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2dbb0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2dbc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2dbd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2dbe0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2dbf0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2dc00 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2dc10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2dc20 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2dc30 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2dc40 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2dc50 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2dc60 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2dc70 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2dc80 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2dc90 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2dca0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2dcb0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2dcc0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2dcd0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2dce0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2dcf0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2dd00 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2dd10 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2dd20 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2dd30 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2dd40 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2dd50 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2dd60 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2dd70 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2dd80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2dd90 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2dda0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2ddb0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2ddc0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2ddd0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2dde0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2ddf0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2de00 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2de10 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2de20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2de30 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2de40 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2de50 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2de60 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2de70 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2de80 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2de90 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2dea0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2deb0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2dec0 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2ded0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2dee0 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2def0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2df00 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2df10 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2df20 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2df30 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2df40 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2df50 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2df60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2df70 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2df80 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2df90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2dfa0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2dfb0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2dfc0 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2dfd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2dfe0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2dff0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2e000 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2e010 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f  _prepare_v3()] o
2e020 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2e030 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2e040 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2e050 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2e060 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2e070 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2e080 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2e090 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2e0a0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2e0b0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2e0c0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2e0d0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2e0e0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2e0f0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2e100 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2e110 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2e120 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2e130 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2e140 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2e150 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2e160 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2e170 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2e180 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e190 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2e1a0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2e1b0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2e1c0 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2e1d0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2e1e0 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2e1f0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2e200 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2e210 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2e220 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2e230 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2e240 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2e250 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2e260 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2e270 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2e280 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2e290 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2e2a0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2e2b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2e2c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2e2d0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2e2e0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2e2f0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2e300 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2e310 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2e320 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2e330 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2e340 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2e350 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2e360 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2e370 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2e380 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2e390 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2e3a0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2e3b0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2e3c0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2e3d0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2e3e0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2e3f0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2e400 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2e410 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2e420 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2e430 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2e440 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2e450 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2e460 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2e470 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e480 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2e490 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2e4a0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2e4b0 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2e4c0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2e4d0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2e4e0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2e4f0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2e500 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2e510 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2e520 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2e530 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2e540 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2e550 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2e560 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2e570 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2e580 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2e590 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2e5a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2e5b0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2e5c0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
2e5d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e5e0 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
2e5f0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2e600 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2e610 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2e620 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2e630 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2e640 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2e650 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2e660 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2e670 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2e680 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2e690 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2e6a0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2e6b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2e6c0 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2e6d0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2e6e0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2e6f0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2e700 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2e710 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2e720 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2e730 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2e740 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2e750 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2e760 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2e770 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
2e780 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2e790 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2e7a0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2e7b0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2e7c0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2e7d0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2e7e0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2e7f0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2e800 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2e810 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2e820 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2e830 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2e840 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2e850 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2e860 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2e870 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2e880 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2e890 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2e8a0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2e8b0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2e8c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2e8d0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2e8e0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2e8f0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2e900 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2e910 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2e920 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2e930 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2e940 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2e950 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2e960 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2e970 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2e980 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2e990 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2e9a0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2e9b0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2e9c0 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2e9d0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2e9e0 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2e9f0 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2ea00 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2ea10 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2ea20 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2ea30 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2ea40 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2ea50 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2ea60 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2ea70 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2ea80 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2ea90 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2eaa0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2eab0 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2eac0 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2ead0 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2eae0 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2eaf0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2eb00 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2eb10 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2eb20 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2eb30 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2eb40 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2eb50 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2eb60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2eb70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2eb80 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2eb90 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2eba0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2ebb0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2ebc0 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2ebd0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2ebe0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2ebf0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2ec00 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2ec10 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2ec20 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2ec30 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2ec40 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2ec50 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2ec60 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2ec70 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2ec80 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2ec90 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2eca0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2ecb0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2ecc0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2ecd0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2ece0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2ecf0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2ed00 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2ed10 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
2ed20 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2ed30 6f 69 6e 74 65 72 28 53 2c 49 2c 50 29 20 72 6f  ointer(S,I,P) ro
2ed40 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68 65  utine causes the
2ed50 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   I-th parameter 
2ed60 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  in.** [prepared 
2ed70 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20  statement] S to 
2ed80 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75  have an SQL valu
2ed90 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74  e of NULL, but t
2eda0 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73  o also be.** ass
2edb0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2edc0 20 70 6f 69 6e 74 65 72 20 50 2e 0a 2a 2a 20 5e   pointer P..** ^
2edd0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2ede0 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74 69  _pointer() routi
2edf0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2ee00 6f 20 70 61 73 73 0a 2a 2a 20 68 6f 73 74 2d 6c  o pass.** host-l
2ee10 61 6e 67 75 61 67 65 20 70 6f 69 6e 74 65 72 73  anguage pointers
2ee20 20 69 6e 74 6f 20 5b 61 70 70 6c 69 63 61 74 69   into [applicati
2ee30 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2ee40 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 5e 41  unctions]..** ^A
2ee50 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
2ee60 69 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  is initialized u
2ee70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 69  sing [sqlite3_bi
2ee80 6e 64 5f 70 6f 69 6e 74 65 72 28 29 5d 20 61 70  nd_pointer()] ap
2ee90 70 65 61 72 73 0a 2a 2a 20 74 6f 20 62 65 20 61  pears.** to be a
2eea0 6e 20 6f 72 64 69 6e 61 72 79 20 53 51 4c 20 4e  n ordinary SQL N
2eeb0 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 65 76 65  ULL value to eve
2eec0 72 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  rything other th
2eed0 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  an.** [sqlite3_v
2eee0 61 6c 75 65 5f 70 6f 69 6e 74 65 72 28 29 5d 2e  alue_pointer()].
2eef0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2ef00 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2ef10 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2ef20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2ef30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2ef40 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2ef50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2ef60 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2ef70 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2ef80 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2ef90 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2efa0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2efb0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2efc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2efd0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2efe0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2eff0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2f000 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2f010 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2f020 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2f030 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f040 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2f050 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2f060 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2f070 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2f080 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2f090 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2f0a0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2f0b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2f0c0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2f0d0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2f0e0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2f0f0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2f100 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f110 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2f120 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f130 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2f140 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2f150 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2f160 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2f170 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2f180 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2f190 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2f1a0 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2f1b0 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2f1c0 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2f1d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2f1e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2f1f0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2f200 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2f210 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2f220 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2f230 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2f240 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2f250 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2f260 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2f270 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2f280 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2f290 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2f2a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2f2b0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2f2c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2f2d0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2f2e0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2f2f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2f300 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2f310 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f320 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f330 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2f340 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2f350 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2f360 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2f370 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2f380 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2f390 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2f3a0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2f3b0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2f3c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2f3d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
2f3e0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2f3f0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
2f400 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2f410 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2f420 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2f430 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2f440 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2f450 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2f460 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
2f470 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2f480 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f490 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2f4a0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2f4b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2f4c0 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2f4d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2f4e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2f4f0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2f500 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2f510 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2f520 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2f530 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2f540 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
2f550 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2f560 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
2f570 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2f580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f590 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
2f5a0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
2f5b0 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
2f5c0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2f5d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f5e0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
2f5f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2f600 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
2f610 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ter(sqlite3_stmt
2f620 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 29 3b 0a  *, int, void*);.
2f630 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2f640 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2f650 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2f660 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t n);.int sqlite
2f670 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
2f680 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2f690 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
2f6a0 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2f6b0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2f6c0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2f6d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2f6e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2f6f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2f700 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2f710 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2f720 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2f730 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2f740 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2f750 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2f760 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2f770 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2f780 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2f790 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2f7a0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2f7b0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2f7c0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2f7d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2f7e0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2f7f0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2f800 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2f810 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2f820 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2f830 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2f840 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2f850 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2f860 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2f870 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2f880 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2f890 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2f8a0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2f8b0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2f8c0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2f8d0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2f8e0 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2f8f0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2f900 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2f910 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2f920 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2f930 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2f940 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2f950 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2f960 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2f970 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2f980 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2f990 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2f9a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2f9b0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2f9c0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2f9d0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2f9e0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2f9f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2fa00 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2fa10 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2fa20 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2fa30 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2fa40 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2fa50 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2fa60 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2fa70 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2fa80 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2fa90 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2faa0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2fab0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2fac0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2fad0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2fae0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2faf0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2fb00 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2fb10 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2fb20 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2fb30 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2fb40 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2fb50 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2fb60 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2fb70 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2fb80 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2fb90 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2fba0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2fbb0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2fbc0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2fbd0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2fbe0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2fbf0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2fc00 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2fc10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2fc20 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2fc30 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2fc40 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2fc50 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2fc60 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2fc70 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2fc80 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2fc90 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2fca0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2fcb0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2fcc0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2fcd0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2fce0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2fcf0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2fd00 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2fd10 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2fd20 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2fd30 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2fd40 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
2fd50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f  epare16_v2()], o
2fd60 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2fd70 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v3()]..**.*
2fd80 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2fd90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2fda0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2fdb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2fdc0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2fdd0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2fde0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2fdf0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2fe00 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2fe10 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2fe20 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
2fe30 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
2fe40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2fe50 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
2fe60 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
2fe70 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
2fe80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2fe90 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2fea0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
2feb0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
2fec0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
2fed0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
2fee0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
2fef0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
2ff00 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
2ff10 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2ff20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2ff30 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
2ff40 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
2ff50 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
2ff60 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
2ff70 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
2ff80 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
2ff90 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
2ffa0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
2ffb0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
2ffc0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
2ffd0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
2ffe0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
2fff0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30000 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
30010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
30020 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v3()]..**.** See
30030 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
30040 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30050 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
30060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30070 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
30080 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
30090 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
300a0 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ame()]..*/.int s
300b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
300c0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
300d0 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
300e0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
300f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30100 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
30110 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
30120 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
30130 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30140 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
30150 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
30160 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
30170 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
30180 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
30190 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
301a0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
301b0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
301c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
301d0 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
301e0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
301f0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
30200 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
30210 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
30220 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
30230 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
30240 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
30250 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
30260 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
30270 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30280 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
30290 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
302a0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
302b0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
302c0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
302d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
302e0 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  . ^If this routi
302f0 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ne returns 0, th
30300 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a  at means the .**
30310 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30320 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f  ment] returns no
30330 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
30340 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
30350 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75  .** ^However, ju
30360 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20  st because this 
30370 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30380 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65  a positive numbe
30390 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65  r does not.** me
303a0 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d  an that one or m
303b0 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61  ore rows of data
303c0 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
303d0 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74  d.  ^A SELECT st
303e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20  atement.** will 
303f0 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f  always have a po
30400 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63  sitive sqlite3_c
30410 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75  olumn_count() bu
30420 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  t depending on t
30430 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  he.** WHERE clau
30440 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  se constraints a
30450 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e  nd the table con
30460 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72  tent, it might r
30470 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a  eturn no rows..*
30480 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
30490 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
304a0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
304b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
304c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
304d0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
304e0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
304f0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
30500 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
30510 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30520 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
30530 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
30540 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
30550 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
30560 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
30570 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
30580 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
30590 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
305a0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
305b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
305c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
305d0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
305e0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
305f0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
30600 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
30610 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
30620 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
30630 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
30640 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
30650 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
30660 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
30670 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
30680 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
30690 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
306a0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
306b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
306c0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
306d0 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
306e0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
306f0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
30700 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
30710 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
30720 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
30730 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
30740 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
30750 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
30760 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
30770 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
30780 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
30790 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
307a0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
307b0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
307c0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
307d0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
307e0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
307f0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
30800 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30810 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
30820 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
30830 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
30840 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
30850 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
30860 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
30870 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
30880 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
30890 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
308a0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
308b0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
308c0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
308d0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
308e0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
308f0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
30900 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
30910 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
30920 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
30930 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
30940 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
30950 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
30960 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
30970 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
30980 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
30990 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
309a0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
309b0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
309c0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
309d0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
309e0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
309f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
30a00 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
30a10 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
30a20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30a30 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
30a40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
30a50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30a60 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
30a70 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
30a80 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
30a90 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
30aa0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
30ab0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
30ac0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
30ad0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
30ae0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
30af0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
30b00 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
30b10 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
30b20 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
30b30 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
30b40 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
30b50 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
30b60 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
30b70 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
30b80 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
30b90 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
30ba0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
30bb0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
30bc0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
30bd0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
30be0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
30bf0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
30c00 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
30c10 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
30c20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
30c30 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
30c40 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
30c50 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
30c60 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
30c70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30c80 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
30c90 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
30ca0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
30cb0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
30cc0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
30cd0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
30ce0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
30cf0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
30d00 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
30d10 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
30d20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
30d30 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
30d40 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
30d50 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
30d60 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
30d70 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
30d80 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
30d90 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
30da0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
30db0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
30dc0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
30dd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
30de0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
30df0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
30e00 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
30e10 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
30e20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
30e30 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
30e40 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
30e50 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
30e60 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
30e70 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
30e80 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
30e90 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
30ea0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
30eb0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
30ec0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
30ed0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
30ee0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
30ef0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
30f00 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
30f10 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
30f20 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
30f30 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
30f40 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
30f50 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
30f60 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
30f70 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
30f80 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
30f90 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
30fa0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
30fb0 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
30fc0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
30fd0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
30fe0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
30ff0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
31000 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
31010 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
31020 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
31030 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
31040 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
31050 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
31060 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
31070 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
31080 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
31090 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
310a0 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
310b0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
310c0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
310d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
310e0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
310f0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
31100 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
31110 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
31120 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
31130 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
31140 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
31150 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
31160 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
31170 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
31180 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
31190 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
311a0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
311b0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
311c0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
311d0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
311e0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
311f0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
31200 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
31210 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
31220 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
31230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
31240 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
31250 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
31260 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
31270 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
31280 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
31290 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
312a0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
312b0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
312c0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
312d0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
312e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
312f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
31300 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
31310 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
31320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31330 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
31340 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
31350 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
31360 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
31370 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
31380 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
31390 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
313a0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
313b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
313c0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
313d0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
313e0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
313f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
31400 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
31410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
31420 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
31430 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
31440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31450 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
31460 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
31470 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
31480 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31490 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
314a0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
314b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
314c0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
314d0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
314e0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
314f0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
31500 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
31510 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
31520 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
31530 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
31540 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
31550 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
31560 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
31570 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
31580 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
31590 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
315a0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
315b0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
315c0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
315d0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
315e0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
315f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
31600 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
31610 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
31620 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
31630 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
31640 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
31650 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
31660 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
31670 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
31680 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
31690 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
316a0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
316b0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
316c0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
316d0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
316e0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
316f0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
31700 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
31710 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
31720 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
31730 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
31740 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
31750 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
31760 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
31770 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
31780 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
31790 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
317a0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
317b0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
317c0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
317d0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
317e0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
317f0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
31800 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
31810 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
31820 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
31830 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
31840 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
31850 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
31860 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
31870 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
31880 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
31890 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
318a0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
318b0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
318c0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
318d0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
318e0 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
318f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
31900 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
31910 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31920 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31930 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
31940 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
31950 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
31960 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
31970 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
31980 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
31990 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
319a0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
319b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
319c0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
319d0 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a   using any of.**
319e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
319f0 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
31a00 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
31a10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31a20 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72  e16_v2()],.** or
31a30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31a40 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65  e16_v3()] or one
31a50 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
31a60 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
31a70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
31a80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
31a90 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
31aa0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
31ab0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
31ac0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
31ad0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
31ae0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
31af0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
31b00 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
31b10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
31b20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
31b30 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
31b40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
31b50 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
31b60 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20 69  the newer "vX" i
31b70 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71  nterfaces.** [sq
31b80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
31b90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
31ba0 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
31bb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
31bc0 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
31bd0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
31be0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
31bf0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
31c00 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
31c10 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
31c20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
31c30 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
31c40 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20  the.** new "vX" 
31c50 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
31c60 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
31c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
31c80 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
31c90 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
31ca0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
31cb0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
31cc0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
31cd0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
31ce0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
31cf0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
31d00 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
31d10 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
31d20 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
31d30 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
31d40 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
31d50 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
31d60 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
31d70 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
31d80 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
31d90 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
31da0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
31db0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
31dc0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
31dd0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
31de0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
31df0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
31e00 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
31e10 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
31e20 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
31e30 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
31e40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31e50 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
31e60 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
31e70 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
31e80 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
31e90 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
31ea0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
31eb0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
31ec0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
31ed0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
31ee0 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
31ef0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
31f00 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
31f10 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
31f20 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
31f30 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
31f40 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
31f50 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
31f60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
31f70 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
31f80 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
31f90 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
31fa0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
31fb0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
31fc0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
31fd0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
31fe0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
31ff0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
32000 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
32010 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
32020 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
32030 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
32040 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
32050 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
32060 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
32070 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
32080 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
32090 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
320a0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
320b0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
320c0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
320d0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
320e0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
320f0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
32100 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
32110 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
32120 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
32130 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
32140 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
32150 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
32160 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
32170 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
32180 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
32190 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
321a0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
321b0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
321c0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
321d0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
321e0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
321f0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
32200 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
32210 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
32220 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
32230 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
32240 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
32250 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
32260 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
32270 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
32280 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
32290 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
322a0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
322b0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
322c0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
322d0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
322e0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
322f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32300 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
32310 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32320 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
32330 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
32340 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
32350 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
32360 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
32370 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
32380 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
32390 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
323a0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
323b0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
323c0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
323d0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
323e0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
323f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32400 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
32410 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
32420 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
32430 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
32440 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
32450 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
32460 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
32470 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
32480 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
32490 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
324a0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
324b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
324c0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
324d0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
324e0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
324f0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
32500 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
32510 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
32520 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
32530 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
32540 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
32550 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
32560 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
32570 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
32580 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
32590 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
325a0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
325b0 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
325c0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
325d0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
325e0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
325f0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
32600 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
32610 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
32620 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32630 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
32640 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
32650 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
32660 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
32670 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b  ().  But after [
32680 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
32690 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32  ] ([dateof:3.6.2
326a0 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  3.1],.** sqlite3
326b0 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
326c0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
326d0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
326e0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
326f0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
32700 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
32710 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
32720 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
32730 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
32740 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
32750 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
32760 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
32770 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
32780 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
32790 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
327a0 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
327b0 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
327c0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
327d0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
327e0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
327f0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
32800 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
32810 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
32820 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
32830 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
32840 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
32850 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
32860 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
32870 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
32880 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
32890 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
328a0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
328b0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
328c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
328d0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
328e0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
328f0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
32900 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
32910 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
32920 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
32930 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
32940 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
32950 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
32960 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
32970 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
32980 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
32990 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
329a0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
329b0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
329c0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
329d0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
329e0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
329f0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
32a00 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
32a10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32a20 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v3()] or [sqlit
32a30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
32a40 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
32a50 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
32a60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
32a70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74  are16_v3()] inst
32a80 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
32a90 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
32aa0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
32ab0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
32ac0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
32ad0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
32ae0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
32af0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
32b00 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
32b10 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
32b20 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
32b30 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
32b40 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  es is recommende
32b50 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
32b60 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
32b70 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
32b80 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
32b90 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
32ba0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54  esult set.** MET
32bb0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
32bc0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
32bd0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
32be0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
32bf0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
32c00 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
32c10 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
32c20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
32c30 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
32c40 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
32c50 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
32c60 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
32c70 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
32c80 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
32c90 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
32ca0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
32cb0 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
32cc0 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
32cd0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
32ce0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
32cf0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
32d00 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
32d10 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
32d20 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
32d30 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
32d40 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
32d50 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
32d60 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
32d70 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
32d80 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
32d90 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
32da0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
32db0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
32dc0 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
32dd0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
32de0 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
32df0 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
32e00 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
32e10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
32e20 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
32e30 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
32e40 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
32e50 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
32e60 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
32e70 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
32e80 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
32e90 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
32ea0 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
32eb0 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
32ec0 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
32ed0 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
32ee0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
32ef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
32f00 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
32f10 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
32f20 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
32f30 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32f40 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
32f50 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
32f60 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
32f70 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
32f80 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
32f90 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
32fa0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
32fb0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
32fc0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
32fd0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
32fe0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
32ff0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
33000 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
33010 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
33020 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
33030 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
33040 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
33050 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
33060 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
33070 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
33080 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
33090 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
330a0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
330b0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
330c0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
330d0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
330e0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
330f0 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
33100 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
33110 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
33120 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
33130 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
33140 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
33150 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
33160 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
33170 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
33180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
33190 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
331a0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
331b0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
331c0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
331d0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
331e0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
331f0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
33200 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
33210 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
33220 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
33230 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
33240 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
33250 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
33260 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
33270 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
33280 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
33290 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
332a0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
332b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
332c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
332d0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
332e0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
332f0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
33300 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
33310 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
33320 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
33330 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
33340 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
33350 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
33360 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
33370 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
33380 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
33390 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
333a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
333b0 65 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v3()] or one o
333c0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
333d0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
333e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
333f0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
33400 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
33410 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
33420 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
33430 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
33440 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
33450 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
33460 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
33470 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
33480 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
33490 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
334a0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
334b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
334c0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
334d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
334e0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
334f0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
33500 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
33510 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
33520 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
33530 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
33540 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
33550 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33560 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
33570 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
33580 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
33590 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
335a0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
335b0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
335c0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
335d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
335e0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
335f0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
33600 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
33610 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
33620 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
33630 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
33640 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
33650 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
33660 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33670 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
33680 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
33690 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
336a0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
336b0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
336c0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
336d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
336e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
336f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
33700 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
33710 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
33720 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
33730 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
33740 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
33750 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
33760 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
33770 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
33780 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
33790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
337a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
337b0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
337c0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
337d0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
337e0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
337f0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
33800 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
33810 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
33820 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
33830 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
33840 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
33850 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
33860 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
33870 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
33880 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
33890 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
338a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
338b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
338c0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
338d0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
338e0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
338f0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
33900 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
33910 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
33920 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
33930 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
33940 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
33950 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
33960 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
33970 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
33980 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
33990 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
339a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
339b0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
339c0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
339d0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
339e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
339f0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
33a00 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
33a10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33a20 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
33a30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
33a40 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
33a50 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
33a60 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
33a70 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
33a80 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
33a90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33aa0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
33ab0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
33ac0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
33ad0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
33ae0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
33af0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
33b00 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
33b10 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
33b20 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
33b30 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
33b40 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
33b50 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
33b60 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
33b70 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
33b80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
33b90 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
33ba0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
33bb0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
33bc0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
33bd0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
33be0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
33bf0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
33c00 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
33c10 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
33c20 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
33c30 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
33c40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
33c50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
33c60 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
33c70 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
33c80 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
33c90 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
33ca0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
33cb0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
33cc0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
33cd0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
33ce0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
33cf0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
33d00 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
33d10 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
33d20 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
33d30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33d40 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
33d50 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
33d60 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
33d70 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
33d80 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
33d90 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
33da0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
33db0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
33dc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
33dd0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
33de0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33df0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
33e00 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
33e10 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
33e20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
33e30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
33e40 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
33e50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33e60 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
33e70 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
33e80 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
33e90 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
33ea0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
33eb0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
33ec0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
33ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33ee0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
33ef0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
33f00 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
33f10 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
33f20 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
33f30 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
33f40 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
33f50 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
33f60 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
33f70 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
33f80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33f90 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
33fa0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
33fb0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
33fc0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
33fd0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
33fe0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
33ff0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
34000 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
34010 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
34020 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  ointer..**.** <b
34030 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54  >Warning:</b> ^T
34040 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
34050 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
34060 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
34070 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
34080 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34090 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20  ue] object.  In 
340a0 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  a multithreaded 
340b0 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20  environment,.** 
340c0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
340d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
340e0 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  ect may only be 
340f0 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68  used safely with
34100 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
34110 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
34120 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34130 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
34140 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
34150 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34160 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
34170 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
34180 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
34190 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
341a0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
341b0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
341c0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
341d0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
341e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
341f0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
34200 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34210 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65  bytes()], the be
34220 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68  havior is not th
34230 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20  readsafe..**.** 
34240 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
34250 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
34260 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
34270 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
34280 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
34290 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
342a0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
342b0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
342c0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
342d0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
342e0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
342f0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
34300 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
34310 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
34320 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
34330 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
34340 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
34350 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
34360 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
34370 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
34380 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
34390 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
343a0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
343b0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
343c0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
343d0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
343e0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
343f0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
34400 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
34410 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
34420 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
34430 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
34440 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
34450 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
34460 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
34470 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
34480 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
34490 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
344a0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
344b0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
344c0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
344d0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
344e0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
344f0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
34500 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
34510 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
34520 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
34530 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
34540 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
34550 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
34560 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
34570 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
34580 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
34590 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
345a0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
345b0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
345c0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
345d0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
345e0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
345f0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
34600 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
34610 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
34620 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
34630 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
34640 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
34650 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
34660 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
34670 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
34680 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
34690 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
346a0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
346b0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
346c0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
346d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
346e0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
346f0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
34700 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
34710 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
34720 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
34730 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
34740 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
34750 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
34760 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
34770 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
34780 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
34790 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
347a0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
347b0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
347c0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
347d0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
347e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
347f0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
34800 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
34810 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
34820 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
34830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34840 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
34850 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
34860 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
34870 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
34880 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
34890 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
348a0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
348b0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
348c0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
348d0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
348e0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
348f0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
34900 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
34910 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
34920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34930 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
34940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34950 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
34960 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
34970 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
34980 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
34990 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
349a0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
349b0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
349c0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
349d0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
349e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
349f0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
34a00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
34a10 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
34a20 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
34a30 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
34a40 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
34a50 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
34a60 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
34a70 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
34a80 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
34a90 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
34aa0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
34ab0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
34ac0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
34ad0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
34ae0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
34af0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
34b00 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
34b10 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
34b20 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
34b30 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
34b40 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
34b50 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
34b60 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
34b70 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
34b80 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
34b90 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
34ba0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
34bb0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
34bc0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
34bd0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
34be0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
34bf0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
34c00 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
34c10 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
34c20 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
34c30 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
34c40 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
34c50 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
34c60 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
34c70 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
34c80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
34c90 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  st policy is to 
34ca0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
34cb0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
34cc0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
34cd0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
34ce0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
34cf0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
34d00 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
34d10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34d20 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
34d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34d40 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
34d50 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
34d60 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
34d70 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
34d80 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
34d90 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
34da0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
34db0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
34dc0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
34dd0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
34de0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
34df0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
34e00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34e10 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
34e20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
34e30 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
34e40 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
34e50 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
34e60 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
34e70 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
34e80 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
34e90 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
34ea0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
34eb0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
34ec0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
34ed0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
34ee0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
34ef0 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
34f00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
34f10 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
34f20 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
34f30 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
34f40 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
34f50 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
34f60 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
34f70 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
34f80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34f90 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
34fa0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
34fb0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
34fc0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
34fd0 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
34fe0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
34ff0 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
35000 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
35010 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
35020 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
35030 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
35040 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
35050 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
35060 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
35070 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
35080 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
35090 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74  lly.  Do <em>not
350a0 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70  </em> pass the p
350b0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
350c0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
350d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
350e0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
350f0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
35100 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
35110 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
35120 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
35130 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
35140 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
35150 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
35160 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
35170 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
35180 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
35190 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
351a0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
351b0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
351c0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
351d0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
351e0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
351f0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
35200 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
35210 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
35220 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
35230 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
35240 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
35250 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
35260 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
35270 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
35280 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
35290 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
352a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
352b0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
352c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
352d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
352e0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
352f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
35300 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
35310 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
35320 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
35330 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
35340 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
35350 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
35360 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
35370 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
35380 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
35390 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
353a0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
353b0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
353c0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
353d0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
353e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
353f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
35400 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
35410 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35420 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
35430 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
35440 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
35450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
35460 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
35470 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
35480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
35490 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
354a0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
354b0 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a  t.** DESTRUCTOR:
354c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
354d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
354e0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
354f0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
35500 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
35510 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
35520 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
35530 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
35540 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
35550 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
35560 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
35570 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
35580 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
35590 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
355a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
355b0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
355c0 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
355d0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
355e0 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
355f0 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
35600 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
35610 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
35620 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
35630 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
35640 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
35650 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
35660 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35670 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
35680 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
35690 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
356a0 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
356b0 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
356c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
356d0 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
356e0 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
356f0 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
35700 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
35710 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
35720 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
35730 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
35740 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
35750 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
35760 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
35770 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
35780 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
35790 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
357a0 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
357b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
357c0 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
357d0 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
357e0 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
357f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
35800 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
35810 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
35820 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
35830 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
35840 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
35850 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
35860 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
35870 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
35880 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
35890 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
358a0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
358b0 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
358c0 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
358d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
358e0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
358f0 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
35900 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
35910 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
35920 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
35930 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
35940 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
35950 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
35960 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
35970 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
35980 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35990 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
359a0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
359b0 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  bject.** METHOD:
359c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
359d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
359e0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
359f0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
35a00 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
35a10 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
35a20 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
35a30 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
35a40 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
35a50 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
35a60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
35a70 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
35a80 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
35a90 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
35aa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
35ab0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
35ac0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
35ad0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
35ae0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
35af0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
35b00 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
35b10 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
35b20 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
35b30 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
35b40 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
35b50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
35b60 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
35b70 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
35b80 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
35b90 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
35ba0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
35bb0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
35bc0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
35bd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35be0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
35bf0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
35c00 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
35c10 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
35c20 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
35c30 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
35c40 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
35c50 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
35c60 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
35c70 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
35c80 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
35c90 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
35ca0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
35cb0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
35cc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
35cd0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
35ce0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
35cf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
35d00 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
35d10 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
35d20 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
35d30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
35d40 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
35d50 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
35d60 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
35d70 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
35d80 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
35d90 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
35da0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
35db0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
35dc0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
35dd0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
35de0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
35df0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
35e00 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
35e10 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
35e20 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
35e30 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
35e40 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
35e50 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
35e60 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
35e70 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
35e80 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
35e90 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
35ea0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
35eb0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
35ec0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
35ed0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
35ee0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
35ef0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
35f00 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
35f10 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
35f20 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
35f30 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
35f40 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
35f50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
35f60 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
35f70 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
35f80 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
35f90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
35fa0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
35fb0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
35fc0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
35fd0 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
35fe0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
35ff0 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
36000 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
36010 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
36020 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
36030 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
36040 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
36050 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
36060 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
36070 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
36080 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36090 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
360a0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
360b0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
360c0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
360d0 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
360e0 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
360f0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
36100 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
36110 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
36120 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
36130 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
36140 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36150 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
36160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
36170 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
36180 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
36190 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
361a0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
361b0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
361c0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
361d0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
361e0 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
361f0 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
36200 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
36210 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
36220 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
36230 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
36240 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
36250 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
36260 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
36270 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
36280 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
36290 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
362a0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
362b0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
362c0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
362d0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
362e0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
362f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
36300 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
36310 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
36320 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
36330 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
36340 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
36350 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
36360 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
36370 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
36380 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
36390 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
363a0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
363b0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
363c0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
363d0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
363e0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
363f0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
36400 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
36410 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
36420 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
36430 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
36440 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
36450 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
36460 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
36470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
36480 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
36490 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
364a0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
364b0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
364c0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
364d0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
364e0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
364f0 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
36500 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
36510 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
36520 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
36530 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
36540 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
36550 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
36560 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
36570 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
36580 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
36590 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
365a0 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
365b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
365c0 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
365d0 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
365e0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
365f0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
36600 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
36610 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
36620 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
36630 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
36640 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
36650 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
36660 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
36670 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
36680 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
36690 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
366a0 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
366b0 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
366c0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
366d0 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
366e0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
366f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
36700 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
36710 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
36720 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
36730 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
36740 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
36750 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
36760 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
36770 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
36780 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
36790 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
367a0 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
367b0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
367c0 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
367d0 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
367e0 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
367f0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
36800 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
36810 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
36820 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
36830 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
36840 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
36850 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
36860 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
36870 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
36880 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
36890 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
368a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
368b0 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
368c0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
368d0 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
368e0 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
368f0 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
36900 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
36910 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
36920 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
36930 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
36940 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
36950 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
36960 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
36970 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
36980 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
36990 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
369a0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
369b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
369c0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
369d0 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
369e0 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
369f0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
36a00 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
36a10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
36a20 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
36a30 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
36a40 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
36a50 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
36a60 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
36a70 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
36a80 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
36a90 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
36aa0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
36ab0 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
36ac0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
36ad0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
36ae0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
36af0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
36b00 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
36b10 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
36b20 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
36b30 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
36b40 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
36b50 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
36b60 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
36b70 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
36b80 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
36b90 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
36ba0 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
36bb0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
36bc0 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
36bd0 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
36be0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
36bf0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
36c00 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
36c10 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
36c20 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
36c30 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
36c40 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
36c50 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
36c60 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
36c70 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
36c80 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
36c90 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
36ca0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
36cb0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
36cc0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
36cd0 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
36ce0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
36cf0 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
36d00 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
36d10 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
36d20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36d30 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
36d40 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
36d50 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
36d60 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
36d70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36d80 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
36d90 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
36da0 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
36db0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
36dc0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
36dd0 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
36de0 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
36df0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
36e00 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
36e10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
36e20 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
36e30 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
36e40 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
36e50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36e60 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
36e70 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
36e80 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
36e90 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
36ea0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
36eb0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
36ec0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
36ed0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
36ee0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
36ef0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
36f00 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
36f10 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
36f20 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
36f30 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
36f40 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
36f50 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
36f60 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
36f70 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
36f80 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
36f90 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
36fa0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
36fb0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
36fc0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
36fd0 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
36fe0 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
36ff0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
37000 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
37010 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
37020 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
37030 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
37040 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
37050 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
37060 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
37070 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
37080 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
37090 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
370a0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
370b0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
370c0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
370d0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
370e0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
370f0 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
37100 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
37110 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
37120 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
37130 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
37140 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
37150 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
37160 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
37170 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
37180 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
37190 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
371a0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
371b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
371c0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
371d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
371e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
371f0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
37200 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
37210 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
37220 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
37230 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
37240 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37250 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
37260 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
37270 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
37280 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
37290 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
372a0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
372b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
372c0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
372d0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
372e0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
372f0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
37300 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
37310 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
37320 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
37330 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37340 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
37350 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
37360 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
37370 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
37380 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
37390 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
373a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
373b0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
373c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
373d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
373e0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
373f0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
37400 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
37410 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
37420 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
37430 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
37440 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
37450 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
37460 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
37470 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37480 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
37490 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
374a0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
374b0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
374c0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
374d0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
374e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
374f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
37500 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
37510 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
37520 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
37530 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
37540 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
37550 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
37560 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
37570 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
37580 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
37590 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
375a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
375b0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
375c0 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
375d0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
375e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
375f0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
37600 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
37610 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
37620 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
37630 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
37640 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
37650 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
37660 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
37670 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37680 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
37690 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37      /* IMP: R-37
376a0 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65  514-35566 */.#de
376b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
376c0 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20  6LE        2    
376d0 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d  /* IMP: R-03371-
376e0 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65  37637 */.#define
376f0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
37700 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49         3    /* I
37710 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35  MP: R-51971-3415
37720 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
37730 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
37740 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
37750 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
37770 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
37780 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63    5    /* Deprec
37790 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ated */.#define 
377a0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
377b0 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
377c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
377d0 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
377e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
377f0 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a  Function Flags.*
37800 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
37810 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64  ants may be ORed
37820 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74   together with t
37830 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  he .** [SQLITE_U
37840 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20  TF8 | preferred 
37850 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61  text encoding] a
37860 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
37870 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ument.** to [sql
37880 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37890 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
378a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
378b0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
378c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
378d0 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  nction_v2()]..*/
378e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
378f0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20  DETERMINISTIC   
37900 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41   0x800../*.** CA
37910 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
37920 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
37930 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
37940 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
37950 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
37960 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
37970 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
37980 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
37990 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
379a0 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
379b0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
379c0 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
379d0 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
379e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
379f0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
37a00 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
37a10 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e  unctions.  To en
37a20 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d  courage programm
37a30 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ers to avoid.** 
37a40 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
37a50 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70   we will not exp
37a60 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64  lain what they d
37a70 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
37a80 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
37a90 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
37aa0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
37ab0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
37ac0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
37ad0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
37ae0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
37af0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
37b00 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
37b10 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
37b20 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
37b30 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
37b40 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
37b50 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
37b60 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
37b70 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
37b80 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
37b90 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
37ba0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
37bb0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
37bc0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
37bd0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
37be0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
37bf0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
37c00 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
37c10 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
37c20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
37c30 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
37c40 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
37c50 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
37c60 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
37c70 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
37c80 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  ue.**.** The C-l
37c90 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
37ca0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
37cb0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
37cc0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
37cd0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
37ce0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
37cf0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
37d00 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
37d10 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
37d20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a  or aggregate.  .
37d30 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
37d40 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
37d50 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
37d60 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
37d70 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
37d80 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
37d90 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
37da0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
37db0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
37dc0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
37dd0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
37de0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
37df0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
37e00 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
37e10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
37e20 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
37e30 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
37e40 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
37e50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
37e60 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
37e70 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
37e80 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37e90 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
37ea0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
37eb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
37ec0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
37ed0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
37ee0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
37ef0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
37f00 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
37f10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
37f20 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
37f30 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
37f40 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37f50 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
37f60 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
37f70 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
37f80 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
37f90 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
37fa0 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
37fb0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
37fc0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
37fd0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
37fe0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
37ff0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
38000 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
38010 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
38020 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69  that these routi
38030 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
38040 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
38050 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
38060 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
38070 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
38080 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
38090 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
380a0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
380b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
380c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
380d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
380e0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
380f0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
38100 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
38110 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
38120 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
38130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
38140 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
38150 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
38160 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
38170 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
38180 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
38190 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
381a0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
381b0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
381c0 49 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  If [sqlite3_valu
381d0 65 5d 20 6f 62 6a 65 63 74 20 56 20 77 61 73 20  e] object V was 
381e0 69 6e 69 74 69 61 6c 69 7a 65 64 20 0a 2a 2a 20  initialized .** 
381f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
38200 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c  ind_pointer(S,I,
38210 50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  P)] or [sqlite3_
38220 72 65 73 75 6c 74 5f 70 6f 69 6e 74 65 72 28 43  result_pointer(C
38230 2c 50 29 5d 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  ,P)], then.** sq
38240 6c 69 74 65 33 5f 76 61 6c 75 65 5f 70 6f 69 6e  lite3_value_poin
38250 74 65 72 28 56 29 20 77 69 6c 6c 20 72 65 74 75  ter(V) will retu
38260 72 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50  rn the pointer P
38270 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 0a 2a 2a  .  Otherwise,.**
38280 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 70   sqlite3_value_p
38290 6f 69 6e 74 65 72 28 56 29 20 72 65 74 75 72 6e  ointer(V) return
382a0 73 20 61 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  s a NULL..**.** 
382b0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
382c0 6c 75 65 5f 74 79 70 65 28 56 29 20 69 6e 74 65  lue_type(V) inte
382d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
382e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
382f0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
38300 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
38310 69 74 69 61 6c 20 64 61 74 61 74 79 70 65 20 6f  itial datatype o
38320 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
38330 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
38340 56 2e 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  V. The returned 
38350 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
38360 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
38370 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
38380 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
38390 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
383a0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
383b0 4c 4c 5d 2e 29 5e 0a 2a 2a 20 4f 74 68 65 72 20  LL].)^.** Other 
383c0 69 6e 74 65 72 66 61 63 65 73 20 6d 69 67 68 74  interfaces might
383d0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
383e0 74 79 70 65 20 66 6f 72 20 61 6e 20 73 71 6c 69  type for an sqli
383f0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
38400 2e 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  ..** For example
38410 2c 20 69 66 20 74 68 65 20 64 61 74 61 74 79 70  , if the datatyp
38420 65 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 53  e is initially S
38430 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 61 6e  QLITE_INTEGER an
38440 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
38450 75 65 5f 74 65 78 74 28 56 29 20 69 73 20 63 61  ue_text(V) is ca
38460 6c 6c 65 64 20 74 6f 20 65 78 74 72 61 63 74 20  lled to extract 
38470 61 20 74 65 78 74 20 76 61 6c 75 65 20 66 6f 72  a text value for
38480 20 74 68 61 74 0a 2a 2a 20 69 6e 74 65 67 65 72   that.** integer
38490 2c 20 74 68 65 6e 20 73 75 62 73 65 71 75 65 6e  , then subsequen
384a0 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  t calls to sqlit
384b0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29  e3_value_type(V)
384c0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 0a 2a 2a   might return.**
384d0 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 20 20 57   SQLITE_TEXT.  W
384e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 20  hether or not a 
384f0 70 65 72 73 69 73 74 65 6e 74 20 69 6e 74 65 72  persistent inter
38500 6e 61 6c 20 64 61 74 61 74 79 70 65 20 63 6f 6e  nal datatype con
38510 76 65 72 73 69 6f 6e 0a 2a 2a 20 6f 63 63 75 72  version.** occur
38520 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  s is undefined a
38530 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
38540 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  om one release o
38550 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
38560 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  next..**.** ^(Th
38570 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
38580 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
38590 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
385a0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
385b0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
385c0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
385d0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
385e0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
385f0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
38600 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
38610 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
38620 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
38630 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
38640 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
38650 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
38660 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
38670 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
38680 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
38690 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
386a0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
386b0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
386c0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
386d0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
386e0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
386f0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
38700 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
38710 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
38720 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
38730 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
38740 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
38750 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
38760 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
38770 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
38780 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
38790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
387a0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
387b0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
387c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
387d0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
387