/ Hex Artifact Content
Login

Artifact 77f4bee882ad4999bf04cf011e1c4cd7f1c6488e290764f3fb46833810447c5d:


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 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
44f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4500: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4510: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4520: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4530: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4540: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4550: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4560: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4570: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4580: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4590: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
45a0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
45b0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
45e0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
45f0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4600: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4610: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4620: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4630: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4640: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4650: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4660: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4670: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
46a0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
46b0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
46c0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
46d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
46e0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
46f0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4700: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4710: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4730: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4740: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4750: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4760: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4780: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4790: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
47a0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
47b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
47c0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
47d0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
47e0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
47f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4800: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4810: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4820: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4830: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4840: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4850: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4860: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4870: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4880: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4890: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
48a0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
48b0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
48c0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
48d0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
48f0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4900: 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23 64  * Not used */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4920: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4930: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4940: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4960: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4970: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4980: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4990: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49b0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49c0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49d0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
49e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
49f0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a00: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a10: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a20: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a30: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a40: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a50: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a60: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a70: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4a80: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4a90: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4aa0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ab0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ac0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4ad0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4af0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b00: 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23  /* Not used */.#
4b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4b20: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4b30: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4b40: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4b50: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b70: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4b80: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4b90: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4ba0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4bc0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4bd0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4be0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4bf0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4c00: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4c10: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4c20: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4c30: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4c40: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4c50: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4c60: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4c70: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c90: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ca0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4cb0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4cc0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4cd0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4ce0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4cf0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4d00: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4d10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4d20: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4d30: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4d40: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4d50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4d60: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4d70: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4d80: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4d90: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4da0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4db0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4dc0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4dd0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4de0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4df0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4e00: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4e10: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4e20: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4e30: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4e40: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e50: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e60: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e70: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e90: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74  rsion 3.3.8 [dat
4ea0: 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e  eof:3.3.8].** an
4eb0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4ec0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4ed0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4ee0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4ef0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4f00: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4f10: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4f20: 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20  These [extended 
4f30: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72  result codes] ar
4f40: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4f50: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f60: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4f70: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4f80: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4f90: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4fa0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20  t_codes()] API. 
4fb0: 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65   Or, the extende
4fc0: 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  d code for.** th
4fd0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72  e most recent er
4fe0: 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69  ror can be obtai
4ff0: 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
5000: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
5010: 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64  rrcode()]..*/.#d
5020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5030: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
5040: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5050: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
5060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5070: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
5080: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5090: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
50a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50b0: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
50c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50d0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
50f0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
5100: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5110: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5120: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5130: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
5140: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5150: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5160: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
5170: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
5180: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5190: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
51a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
51b0: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
51c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
51d0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
51e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
51f0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5200: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
5230: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5240: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
5250: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5260: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
5270: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5280: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
5290: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52a0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
52b0: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
52c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
52d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52e0: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
52f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5300: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
5310: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5320: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
5330: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5340: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
5350: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5360: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
5370: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
5380: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
5390: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53a0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
53b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
53c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
53d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53e0: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
53f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5400: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
5410: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5420: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
5430: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
5440: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
5450: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5460: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
5470: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
5480: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
5490: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54a0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
54b0: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
54c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
54d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54e0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
54f0: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
5500: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
5510: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5520: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
5530: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5540: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
5550: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5560: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
5570: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5580: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
5590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55a0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
55b0: 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c  _NOENT      (SQL
55c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c  ITE_IOERR | (23<
55d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55e0: 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20  ITE_IOERR_MMAP  
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5600: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c  ITE_IOERR | (24<
5610: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5620: 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d  ITE_IOERR_GETTEM
5630: 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  PPATH       (SQL
5640: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c  ITE_IOERR | (25<
5650: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5660: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41  ITE_IOERR_CONVPA
5670: 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TH          (SQL
5680: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c  ITE_IOERR | (26<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56a0: 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20  ITE_IOERR_VNODE 
56b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
56c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c  ITE_IOERR | (27<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20  ITE_IOERR_AUTH  
56f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5700: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c  ITE_IOERR | (28<
5710: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5720: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
5730: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
5740: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
5770: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
5780: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5790: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57a0: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53  QLITE_BUSY_SNAPS
57b0: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53  HOT           (S
57c0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
57d0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
57e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57f0: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
5800: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5810: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5820: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5830: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
5840: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5850: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5870: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
5880: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5890: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
58b0: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
58d0: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
58e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58f0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5900: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5910: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5930: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5940: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5950: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5960: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5970: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
5980: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
5990: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
59a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
59b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
59c0: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
59d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
59e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
59f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44  QLITE_READONLY_D
5a00: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53  BMOVED        (S
5a10: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5a20: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a30: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5a40: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5a50: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5a60: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a80: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5a90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5aa0: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ac0: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5ad0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ae0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b00: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5b10: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5b20: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5b50: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5b60: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b70: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b90: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5ba0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bb0: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bd0: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5be0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bf0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c10: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5c20: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c30: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5c60: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5c70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c80: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5c90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ca0: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5cb0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5cc0: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ce0: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5cf0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5d00: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d20: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5d30: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5d40: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d60: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5d70: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5d80: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5d90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5da0: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5db0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5dc0: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5de0: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20  AUTH_USER       
5df0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e00: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AUTH | (1<<8)).#
5e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
5e20: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c  _LOAD_PERMANENTL
5e30: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b  Y     (SQLITE_OK
5e40: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5e50: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5e60: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5e70: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5e80: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5e90: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5ea0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5eb0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5ec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5ed0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5ee0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5ef0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5f00: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5f10: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5f20: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5f30: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5f40: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5f50: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5f60: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5f70: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5f80: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5f90: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5fa0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5fb0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fd0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5fe0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5ff0: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
6000: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6010: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6020: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
6030: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
6040: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
6050: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6060: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
6070: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
6080: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
6090: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60a0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
60b0: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
60c0: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
60d0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60e0: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
60f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6100: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
6110: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6120: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6130: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
6140: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6150: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
6160: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6170: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6180: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
6190: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61a0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
61b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
61c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
61d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61e0: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
61f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6200: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
6210: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
6220: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
6230: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6240: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6250: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6260: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
6270: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
6290: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
62a0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
62b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
62d0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
62e0: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
62f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6300: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
6310: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
6320: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
6330: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6340: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6350: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
6360: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
6370: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6380: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6390: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
63a0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
63b0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
63c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
63d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
63e0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
63f0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
6400: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
6410: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6420: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6430: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
6440: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6450: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
6460: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6470: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6480: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
6490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
64a0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
64b0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
64c0: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
64d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
64e0: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
64f0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6500: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
6510: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
6520: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6530: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
6540: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6550: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6560: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6570: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6580: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6590: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
65a0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
65b0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
65c0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
65d0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
65e0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
65f0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6600: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
6610: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
6620: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6630: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
6640: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6650: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6660: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6670: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6680: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6690: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
66a0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
66b0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
66c0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
66d0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
66e0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
66f0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6700: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6710: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6720: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6730: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6740: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6750: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6760: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6770: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6780: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6790: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
67a0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
67b0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
67c0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
67d0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
67e0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
67f0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6800: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6810: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6820: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6830: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6840: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6850: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6860: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6870: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6880: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6890: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
68a0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
68b0: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
68c0: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
68d0: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
68e0: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
68f0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6900: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6910: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6920: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6930: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6940: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6950: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6960: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6970: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6990: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
69a0: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
69b0: 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c  cates that a fil
69c0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
69d0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
69e0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
69f0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6a00: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6a10: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6a20: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6a30: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6a40: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6a50: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6a60: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6a70: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a90: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ab0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6ad0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6ae0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b50: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b70: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bc0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6be0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6bf0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c30: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6c50: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6c60: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c80: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6cc0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6cd0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6cf0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6d00: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d20: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6d30: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6d40: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6d60: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6d70: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6d80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6d90: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6da0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6db0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6dc0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6dd0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6de0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6df0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6e00: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6e10: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6e20: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6e30: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6e40: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6e50: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6e60: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6e80: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6e90: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6ea0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6eb0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6ec0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6ed0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6ee0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6ef0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6f00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6f10: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6f20: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6f30: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6f40: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6f50: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6f60: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6f70: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6f80: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6f90: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6fa0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6fb0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6fc0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6fd0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6fe0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6ff0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
7000: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
7010: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
7020: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
7030: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
7040: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
7050: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
7060: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
7070: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
7080: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
7090: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
70a0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
70b0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
70c0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
70d0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
70e0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
70f0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
7100: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
7110: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
7120: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7130: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7140: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7150: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7160: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7170: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7180: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7190: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
71a0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
71b0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
71c0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
71d0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
71e0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
71f0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
7200: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7210: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
7220: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7230: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7240: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7250: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7260: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7270: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7280: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7290: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
72a0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
72b0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
72c0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
72d0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
72e0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
72f0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
7300: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7310: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
7320: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7330: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7340: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7350: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7360: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7370: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7380: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7390: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
73a0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
73b0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
73c0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
73d0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
73e0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
73f0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
7400: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7410: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
7420: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7430: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7450: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7460: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7470: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7480: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7490: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
74a0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
74b0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
74c0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
74d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
74e0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
74f0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
7500: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7510: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
7520: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7530: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7540: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7550: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7560: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7570: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7580: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7590: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
75a0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
75b0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
75c0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
75d0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
75e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
75f0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7600: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7610: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
7620: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7630: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7640: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7650: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7660: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7670: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7680: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7690: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
76a0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
76b0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
76c0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
76d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
76e0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
76f0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7700: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7710: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
7720: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7730: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7740: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7750: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7760: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7770: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7780: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7790: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
77a0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
77b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
77c0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
77d0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
77e0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
77f0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7800: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7810: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
7820: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7830: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7840: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7850: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7860: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7870: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7880: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7890: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
78a0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
78b0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
78c0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
78d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
78e0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
78f0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7900: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7910: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7920: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7930: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7940: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7950: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7960: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7970: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7980: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7990: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
79a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
79b0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
79c0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
79d0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
79e0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
79f0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7a00: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7a10: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
7a20: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7a30: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7a40: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7a50: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7a60: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7a70: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7a80: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7a90: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7aa0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7ab0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7ac0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7ad0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7ae0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7af0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7b00: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7b10: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
7b20: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
7b30: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7b40: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7b50: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7b60: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7b70: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7b80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7b90: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ba0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7bc0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7bd0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7be0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7bf0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7c00: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7c10: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7c20: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7c30: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7c40: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7c50: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7c60: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7c70: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7c80: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7c90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7ca0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7cb0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7cc0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7cd0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7ce0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7cf0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7d00: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7d10: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7d20: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7d30: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7d40: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7d50: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7d60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7d70: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7d80: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7d90: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7da0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7db0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7dc0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7dd0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7de0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7df0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7e00: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7e10: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7e20: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7e30: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7e40: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7e50: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7e60: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7e70: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7e80: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7e90: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7ea0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7eb0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7ec0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7ed0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7ee0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7ef0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7f00: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7f10: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7f20: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7f30: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7f40: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7f50: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7f60: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7f70: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7f80: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7f90: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7fa0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7fb0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7fc0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7fd0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7fe0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7ff0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
8000: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
8010: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
8020: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
8030: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
8040: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
8050: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
8060: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
8070: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
8080: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
8090: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
80a0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
80b0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
80c0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
80d0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
80e0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
80f0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
8100: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8110: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8120: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8130: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8140: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8150: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8160: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8170: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8180: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8190: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
81a0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
81b0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
81c0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
81d0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
81e0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
81f0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8200: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8210: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8220: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8230: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8240: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8250: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8260: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8270: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8280: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8290: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
82a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
82b0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
82c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82d0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
82e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82f0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8300: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8310: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8320: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8330: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8340: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8350: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8360: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8370: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8380: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8390: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
83a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
83b0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
83c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
83d0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
83e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83f0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
8400: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a  LE_WHEN_OPEN].**
8410: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8420: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
8430: 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e  ERWRITE].** <li>
8440: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
8450: 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75  MMUTABLE].** </u
8460: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
8470: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8480: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8490: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
84a0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
84b0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
84c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
84d0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
84e0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
84f0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
8500: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
8510: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
8520: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
8530: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
8540: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
8550: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
8560: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8570: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8580: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8590: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
85a0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
85b0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
85c0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
85d0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
85e0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
85f0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
8600: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
8610: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
8620: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8630: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
8640: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8650: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
8660: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
8670: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8680: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8690: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
86a0: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
86b0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
86c0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
86d0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
86e0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
86f0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
8700: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
8710: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
8720: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
8730: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8740: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
8750: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
8760: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
8770: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8780: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8790: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
87a0: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
87b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
87c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
87d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
87e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
87f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8800: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
8810: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
8820: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
8830: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8840: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
8850: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8860: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8870: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8880: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8890: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88a0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
88b0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
88c0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
88d0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
88e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
88f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
8900: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
8910: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
8920: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8930: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
8940: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8950: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8960: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8970: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8980: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8990: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
89a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
89b0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
89c0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
89d0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
89e0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
89f0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
8a00: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8a10: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
8a20: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
8a30: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
8a40: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8a50: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8a60: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8a70: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8a80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8a90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8aa0: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8ab0: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8ac0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8ad0: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8ae0: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
8af0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
8b00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8b10: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
8b20: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
8b30: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
8b40: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8b50: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8b60: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8b70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8b80: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8b90: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8ba0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8bb0: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8bc0: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8bd0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8be0: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8bf0: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
8c00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
8c10: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8c20: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8c30: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
8c40: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8c50: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8c60: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8c70: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8c80: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8c90: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8ca0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8cb0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8cc0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8cd0: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8ce0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
8cf0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8d00: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
8d10: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
8d20: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8d30: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8d40: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8d50: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8d60: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8d70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8d80: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8d90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8da0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8db0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rface..**.** <ul
8dc0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
8dd0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8de0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8df0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8e00: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8e10: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8e20: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8e30: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8e40: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8e50: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8e60: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8e70: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8e80: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8e90: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8ea0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8eb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8ec0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8ed0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8ee0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8ef0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8f00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8f10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8f20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8f30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8f40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8f50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73  g testing and is
8f60: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
8f70: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  when the SQLITE_
8f80: 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  TEST.** compile-
8f90: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75  time option is u
8fa0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  sed..**.** <li>[
8fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8fc0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8fd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8fe0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8ff0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
9000: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
9010: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
9020: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
9030: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9040: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
9050: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
9060: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
9070: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
9080: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
9090: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
90a0: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
90b0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
90c0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
90d0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
90e0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
90f0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
9100: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
9110: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
9120: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
9130: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9140: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
9150: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9160: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9170: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
9180: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
9190: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
91a0: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
91b0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
91c0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
91d0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
91e0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
91f0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
9200: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
9210: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
9220: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
9230: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9240: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
9250: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
9260: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
9270: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
9280: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
9290: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
92a0: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
92b0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
92c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
92d0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
92e0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
92f0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
9300: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
9310: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
9320: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
9330: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
9340: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9350: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9360: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9370: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9380: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9390: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
93a0: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
93b0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
93c0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
93d0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
93e0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
93f0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9400: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9410: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9420: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9430: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9440: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9450: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
9460: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9480: 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  AL_POINTER] opco
9490: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
94a0: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
94b0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
94c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
94d0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
94e0: 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  he journal file 
94f0: 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b  (either.** the [
9500: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
9510: 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d  ] or the [write-
9520: 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20  ahead log]) for 
9530: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9540: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9550: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
9560: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9570: 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  E_POINTER]..**.*
9580: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9590: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
95a0: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
95b0: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
95c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
95d0: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
95e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
95f0: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9600: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9610: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
9620: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
9630: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
9640: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
9650: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
9660: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
9670: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
9680: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
9690: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
96a0: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
96b0: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
96c0: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
96d0: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
96e0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
96f0: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9700: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9710: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
9720: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
9730: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
9740: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
9750: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
9760: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
9770: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9780: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
9790: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
97a0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
97b0: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
97c0: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
97d0: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
97e0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
97f0: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9800: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9810: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
9820: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
9830: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
9840: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
9850: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
9860: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
9870: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9880: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9890: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
98a0: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
98b0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
98c0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
98d0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
98e0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
98f0: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9900: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9910: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9920: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9930: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9940: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9950: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
9960: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9970: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9980: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
9990: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
99a0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
99b0: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
99c0: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
99d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
99e0: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
99f0: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9a00: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9a10: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
9a20: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
9a30: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9a40: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
9a50: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9a60: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9a70: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
9a80: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
9a90: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9aa0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
9ab0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9ac0: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9ad0: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9ae0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9af0: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9b00: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9b10: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b20: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9b30: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
9b40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9b50: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b60: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9b70: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
9b80: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
9b90: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
9ba0: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
9bb0: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
9bc0: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9bd0: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9be0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9bf0: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9c00: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9c10: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
9c20: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
9c30: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9c40: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9c50: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9c60: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
9c70: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
9c80: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
9c90: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
9ca0: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
9cb0: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
9cc0: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9cd0: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9ce0: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9cf0: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9d00: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9d10: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
9d20: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
9d30: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9d40: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9d50: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9d60: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9d70: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9d80: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9d90: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9da0: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9db0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9dc0: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9dd0: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9de0: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9df0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9e00: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9e10: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9e20: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9e30: 65 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20  eger is the new 
9e40: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
9e50: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
9e60: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
9e70: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
9e80: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
9e90: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
9ea0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
9eb0: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
9ec0: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
9ed0: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
9ee0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
9ef0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
9f00: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
9f10: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
9f20: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
9f30: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
9f40: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
9f50: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
9f60: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  red..**.** <li>[
9f70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9f80: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e  RSIST_WAL]].** ^
9f90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9fa0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f  L_PERSIST_WAL] o
9fb0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9fc0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
9fd0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
9fe0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65  [WAL | Write Ahe
9ff0: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e  ad Log] setting.
a000: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
a010: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77  e auxiliary.** w
a020: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61  rite ahead log a
a030: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a040: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20   files used for 
a050: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
a060: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d  rol.** are autom
a070: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
a080: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74   when the latest
a090: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74   connection to t
a0a0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
a0b0: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20  loses.  Setting 
a0c0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
a0d0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65  ode causes those
a0e0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73   files to persis
a0f0: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65  t after.** close
a100: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68  .  Persisting th
a110: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75  e files is usefu
a120: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f  l when other pro
a130: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e  cesses that do n
a140: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65  ot.** have write
a150: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74   permission on t
a160: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e  he directory con
a170: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61  taining the data
a180: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a  base file want.*
a190: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  * to read the da
a1a0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20  tabase file, as 
a1b0: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72  the WAL and shar
a1c0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
a1d0: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e  must exist.** in
a1e0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64   order for the d
a1f0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
a200: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75  adable.  The fou
a210: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a220: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a230: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a240: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a250: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a260: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a270: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a280: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a290: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
a2a0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a2b0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a  le persistent.**
a2c0: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74   WAL mode.  If t
a2d0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a2e0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a2f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a300: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c  e current.** WAL
a310: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74   persistence set
a320: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a330: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a340: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a350: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a360: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a370: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a380: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a390: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
a3a0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
a3b0: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
a3c0: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
a3d0: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
a3e0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
a3f0: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
a400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
a410: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a420: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
a430: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a440: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
a450: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a460: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a470: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a480: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a490: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a4a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a4b0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a4c0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a4d0: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
a4e0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
a4f0: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
a500: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
a510: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a520: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a530: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a540: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
a550: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
a560: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a570: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a580: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
a590: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a5a0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
a5b0: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
a5c0: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
a5d0: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
a5e0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
a5f0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
a600: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
a610: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
a620: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
a630: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
a640: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
a650: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
a660: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
a670: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
a680: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
a690: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
a6a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a6b0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a  FCNTL_VFSNAME]].
a6c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a6d0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
a6e0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
a6f0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
a700: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
a710: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
a720: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
a730: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
a740: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
a750: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
a760: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
a770: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
a780: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
a790: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
a7a0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
a7b0: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
a7c0: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
a7d0: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
a7e0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
a7f0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
a800: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a810: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
a820: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
a830: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
a840: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
a850: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
a860: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
a870: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
a880: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
a890: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
a8a0: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
a8b0: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
a8c0: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
a8d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
a8e0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
a8f0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
a900: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
a910: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
a920: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
a930: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
a940: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
a950: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
a960: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a   use only..**.**
a970: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a980: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
a990: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a9a0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
a9b0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64  TER] opcode find
a9c0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
a9d0: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20  he top-level.** 
a9e0: 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c  [VFSes] currentl
a9f0: 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65  y in use.  ^(The
aa00: 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a   argument X in.*
aa10: 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  * sqlite3_file_c
aa20: 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45  ontrol(db,SQLITE
aa30: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
aa40: 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a  ER,X) must be.**
aa50: 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74   of type "[sqlit
aa60: 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68  e3_vfs] **".  Th
aa70: 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20  is opcodes will 
aa80: 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70  set *X.** to a p
aa90: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
aaa0: 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a  p-level VFS.)^.*
aab0: 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72  * ^When there ar
aac0: 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73  e multiple VFS s
aad0: 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63  hims in the stac
aae0: 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66  k, this opcode f
aaf0: 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65  inds the.** uppe
ab00: 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79  r-most shim only
ab10: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ab20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ab30: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
ab40: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
ab50: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
ab60: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
ab70: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
ab80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
ab90: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
aba0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
abb0: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
abc0: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
abd0: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
abe0: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
abf0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
ac00: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
ac10: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
ac20: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ac30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
ac40: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
ac50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
ac60: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
ac70: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
ac80: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
ac90: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
aca0: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
acb0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
acc0: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
acd0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
ace0: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
acf0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
ad00: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
ad10: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
ad20: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
ad30: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ad40: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
ad50: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
ad60: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
ad70: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
ad80: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
ad90: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
ada0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
adb0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
adc0: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
add0: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
ade0: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
adf0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
ae00: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
ae10: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
ae20: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
ae30: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
ae40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ae50: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ae60: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
ae70: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
ae80: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
ae90: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
aea0: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
aeb0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
aec0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
aed0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
aee0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
aef0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
af00: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
af10: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
af20: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
af30: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
af40: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
af50: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
af60: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66  red statement if
af70: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69   result string i
af80: 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20  s NULL, or that 
af90: 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a  returns a copy.*
afa0: 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
afb0: 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74  string if the st
afc0: 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c  ring is non-NULL
afd0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  ..** ^If the [SQ
afe0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aff0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b000: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
b010: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
b020: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
b030: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
b040: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
b050: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
b060: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
b070: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
b080: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
b090: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
b0a0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
b0b0: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
b0c0: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
b0d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b0e0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b0f0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
b100: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
b110: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
b120: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
b130: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
b140: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
b150: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
b160: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
b170: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b180: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b190: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
b1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b1b0: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
b1c0: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
b1d0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
b1e0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
b1f0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
b200: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
b210: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
b220: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
b230: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
b240: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
b250: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
b260: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
b270: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
b280: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
b290: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
b2a0: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
b2b0: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
b2c0: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
b2d0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
b2e0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
b2f0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
b300: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
b310: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
b320: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
b330: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
b340: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
b350: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
b360: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
b370: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
b380: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
b390: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
b3a0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
b3b0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
b3c0: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
b3d0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
b3e0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
b3f0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
b400: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
b410: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
b420: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
b430: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b440: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
b450: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
b460: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
b470: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b480: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
b490: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
b4a0: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
b4b0: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
b4c0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
b4d0: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
b4e0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
b4f0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
b500: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
b510: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
b520: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
b530: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
b540: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
b550: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
b560: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
b570: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
b580: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
b590: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
b5a0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
b5b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
b5c0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
b5d0: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
b5e0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
b5f0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
b600: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
b610: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
b620: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b630: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b640: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b650: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b660: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b670: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
b680: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
b690: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b6a0: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
b6b0: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
b6c0: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
b6d0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b6e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b6f0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
b700: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
b710: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
b720: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
b730: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
b740: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
b750: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
b760: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
b770: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
b780: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
b790: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
b7a0: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
b7b0: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
b7c0: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
b7d0: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
b7e0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
b7f0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
b800: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
b810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b820: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
b830: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
b840: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
b850: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
b860: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
b870: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
b880: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b890: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
b8a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b8b0: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
b8c0: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
b8d0: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
b8e0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
b8f0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
b900: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
b910: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
b920: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
b930: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
b940: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
b950: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
b960: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
b970: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b980: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
b990: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
b9a0: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
b9b0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
b9c0: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
b9d0: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
b9e0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b9f0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
ba00: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
ba10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
ba20: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
ba30: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ba40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
ba50: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  OVED]].** The [S
ba60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
ba70: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74  MOVED] file cont
ba80: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
ba90: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
baa0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
bab0: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74  n integer and it
bac0: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61   writes a boolea
bad0: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  n into that inte
bae0: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a  ger depending.**
baf0: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e   on whether or n
bb00: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20  ot the file has 
bb10: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f  been renamed, mo
bb20: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ved, or deleted 
bb30: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20  since it.** was 
bb40: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a  first opened..**
bb50: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bb60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
bb70: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
bb80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
bb90: 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d  IN32_GET_HANDLE]
bba0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
bbb0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
bbc0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
bbd0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
bbe0: 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
bbf0: 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65  th a file handle
bc00: 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20  .  This file.** 
bc10: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
bc20: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
bc30: 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  as a pointer to 
bc40: 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61  a native file ha
bc50: 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74  ndle and.** writ
bc60: 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  es the resulting
bc70: 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a   value there..**
bc80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bc90: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
bca0: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
bcb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
bcc0: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
bcd0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
bce0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
bcf0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
bd00: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
bd10: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
bd20: 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68   swap the file h
bd30: 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f  andle with the o
bd40: 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ne.** pointed to
bd50: 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67   by the pArg arg
bd60: 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70  ument.  This cap
bd70: 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20  ability is used 
bd80: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a  during testing.*
bd90: 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  * and only needs
bda0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
bdb0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
bdc0: 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  T is defined..**
bdd0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bde0: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
bdf0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
be00: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
be10: 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74  K] is a signal t
be20: 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20  o the VFS layer 
be30: 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a  that it might.**
be40: 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73   be advantageous
be50: 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65   to block on the
be60: 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69   next WAL lock i
be70: 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f  f the lock is no
be80: 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  t immediately.**
be90: 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65   available.  The
bea0: 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69   WAL subsystem i
beb0: 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61  ssues this signa
bec0: 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a  l during rare.**
bed0: 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69   circumstances i
bee0: 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61  n order to fix a
bef0: 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72   problem with pr
bf00: 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e  iority inversion
bf10: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
bf20: 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74  s should <em>not
bf30: 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66  </em> use this f
bf40: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a  ile-control..**.
bf50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bf60: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a  FCNTL_ZIPVFS]].*
bf70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bf80: 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f  NTL_ZIPVFS] opco
bf90: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
bfa0: 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79  d by zipvfs only
bfb0: 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56  . All other.** V
bfc0: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
bfd0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
bfe0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
bff0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d  LITE_FCNTL_RBU]]
c010: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c020: 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64  FCNTL_RBU] opcod
c030: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c040: 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20   by the special 
c050: 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74  VFS used by.** t
c060: 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e  he RBU extension
c070: 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65   only.  All othe
c080: 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  r VFS should ret
c090: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c0a0: 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20  UND for.** this 
c0b0: 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75  opcode.  .** </u
c0c0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
c0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
c0e0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
c0f0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
c100: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
c110: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c120: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
c130: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
c140: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
c150: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
c160: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
c170: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
c180: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c190: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
c1a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
c1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1c0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
c1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
c1e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c1f0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
c200: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
c210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c220: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
c230: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
c240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c250: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
c260: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
c270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c280: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
c290: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
c2a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2b0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
c2c0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
c2d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c2e0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
c2f0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
c300: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
c310: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c320: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
c330: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
c340: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
c350: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
c360: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
c370: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
c380: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
c390: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
c3a0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
c3b0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
c3c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
c3d0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
c3e0: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
c3f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
c400: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c410: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
c420: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
c430: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
c440: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
c450: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
c460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
c470: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
c480: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
c490: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
c4a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c4b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
c4c0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
c4d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c4e0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20  CNTL_WAL_BLOCK  
c4f0: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23              24.#
c500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c510: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20  NTL_ZIPVFS      
c520: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64             25.#d
c530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c540: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20  TL_RBU          
c550: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65            26.#de
c560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c570: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20  L_VFS_POINTER   
c580: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66           27.#def
c590: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c5a0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
c5b0: 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69          28.#defi
c5c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c5d0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
c5e0: 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e         29.#defin
c5f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
c600: 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20  DB              
c610: 20 20 20 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70        30../* dep
c620: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
c630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c640: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c650: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c660: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
c670: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c680: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
c690: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c6a0: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
c6b0: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c6c0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
c6d0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
c6e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c6f0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
c700: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
c710: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
c720: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
c730: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
c740: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
c750: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
c760: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
c770: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
c780: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
c790: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
c7a0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
c7b0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
c7c0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
c7d0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
c7e0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
c7f0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
c800: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c810: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
c820: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
c830: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c840: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
c850: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c860: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
c870: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
c880: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c890: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73   Loadable Extens
c8a0: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20  ion Thunk.**.** 
c8b0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
c8c0: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f   opaque sqlite3_
c8d0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72  api_routines str
c8e0: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64  ucture is passed
c8f0: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64   as.** the third
c900: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e   parameter to en
c910: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c  try points of [l
c920: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
c930: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74  ns].  This.** st
c940: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20  ructure must be 
c950: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64  typedefed in ord
c960: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  er to work aroun
c970: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69  d compiler warni
c980: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70  ngs.** on some p
c990: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70  latforms..*/.typ
c9a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
c9b0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
c9c0: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
c9d0: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tines;../*.** CA
c9e0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c9f0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
ca00: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
ca10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
ca20: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
ca30: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
ca40: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
ca50: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
ca60: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
ca70: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
ca80: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
ca90: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
caa0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
cab0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
cac0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
cad0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
cae0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
caf0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
cb00: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
cb10: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
cb20: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
cb30: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
cb40: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
cb50: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
cb60: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
cb70: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
cb80: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
cb90: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
cba0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
cbb0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
cbc0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
cbd0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
cbe0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
cbf0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
cc00: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
cc10: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
cc20: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
cc30: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
cc40: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
cc50: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
cc60: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
cc70: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
cc80: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
cc90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
cca0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
ccb0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
ccc0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
ccd0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
cce0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
ccf0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
cd00: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
cd10: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
cd20: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
cd30: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
cd40: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
cd50: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
cd60: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
cd70: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
cd80: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
cd90: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
cda0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
cdb0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
cdc0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
cdd0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
cde0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
cdf0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
ce00: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
ce10: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
ce20: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
ce30: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ce40: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
ce50: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
ce60: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
ce70: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
ce80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
ce90: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
cea0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
ceb0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
cec0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
ced0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
cee0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
cef0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
cf00: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
cf10: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
cf20: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
cf30: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
cf40: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
cf50: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
cf60: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
cf70: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
cf80: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
cf90: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
cfa0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
cfb0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
cfc0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
cfd0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
cfe0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
cff0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
d000: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
d010: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
d020: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
d030: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
d040: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
d050: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
d060: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d070: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
d080: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
d090: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
d0a0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
d0b0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
d0c0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
d0d0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
d0e0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
d0f0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
d100: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d110: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
d120: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
d130: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
d140: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
d150: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
d160: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
d170: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
d180: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
d190: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
d1a0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
d1b0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
d1c0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
d1d0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
d1e0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
d1f0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
d200: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
d210: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
d220: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
d230: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
d240: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
d250: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
d260: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
d270: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
d280: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
d290: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
d2a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
d2b0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
d2c0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
d2d0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
d2e0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
d2f0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
d300: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
d310: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
d320: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
d330: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
d340: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
d350: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
d360: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
d370: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
d380: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d390: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
d3a0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
d3b0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
d3c0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
d3d0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
d3e0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
d3f0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
d400: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
d410: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
d420: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
d430: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
d440: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
d450: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
d460: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
d470: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
d480: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
d490: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
d4a0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
d4b0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
d4c0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
d4d0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
d4e0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
d4f0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
d500: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
d510: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
d520: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
d530: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
d540: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
d550: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
d560: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
d570: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
d580: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
d590: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
d5a0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
d5b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d5c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
d5d0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d5e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
d5f0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
d600: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
d610: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
d620: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
d630: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
d640: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d650: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
d660: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d670: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
d680: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d690: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
d6a0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
d6b0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
d6c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
d6d0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
d6e0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
d6f0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
d700: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
d710: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
d720: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
d730: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
d740: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
d750: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
d760: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
d770: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
d780: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
d790: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
d7a0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
d7b0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
d7c0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
d7d0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
d7e0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
d7f0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
d800: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
d810: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
d820: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
d830: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
d840: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
d850: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
d860: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
d870: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
d880: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
d890: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
d8a0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
d8b0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
d8c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
d8d0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
d8e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d8f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d900: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d910: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d920: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d930: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d940: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d950: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d960: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d970: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d980: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d990: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d9a0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d9b0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d9c0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
d9d0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d9e0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d9f0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
da00: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
da10: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
da20: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
da30: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
da40: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
da50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
da60: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
da70: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
da80: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
da90: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
daa0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
dab0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
dac0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
dad0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
dae0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
daf0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
db00: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
db10: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
db20: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
db30: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
db40: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
db50: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
db60: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
db70: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
db80: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
db90: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
dba0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
dbb0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
dbc0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
dbd0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
dbe0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
dbf0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
dc00: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
dc10: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
dc20: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
dc30: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
dc40: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
dc50: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
dc60: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
dc70: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
dc80: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
dc90: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
dca0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
dcb0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
dcc0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
dcd0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
dce0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
dcf0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
dd00: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
dd10: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
dd20: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
dd30: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
dd40: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
dd50: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
dd60: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
dd70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
dd80: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
dd90: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
dda0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
ddb0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
ddc0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
ddd0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
dde0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
ddf0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
de00: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
de10: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
de20: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
de30: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
de40: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
de50: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
de60: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
de70: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
de80: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
de90: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
dea0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
deb0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
dec0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
ded0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
dee0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
def0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
df00: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
df10: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
df20: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
df30: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
df40: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
df50: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
df60: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
df70: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
df80: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
df90: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
dfa0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
dfb0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
dfc0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
dfd0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
dfe0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
dff0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
e000: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
e010: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
e020: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
e030: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
e040: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
e050: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
e060: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
e070: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
e080: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
e090: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
e0a0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
e0b0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
e0c0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
e0d0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
e0e0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
e0f0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
e100: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
e110: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
e120: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
e130: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
e140: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
e150: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
e160: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
e170: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
e180: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
e190: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
e1a0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
e1b0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
e1c0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
e1d0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
e1e0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
e1f0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
e200: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
e210: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
e220: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
e230: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
e240: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
e250: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
e260: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
e270: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
e280: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
e290: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
e2a0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
e2b0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
e2c0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
e2d0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
e2e0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
e2f0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
e300: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
e310: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
e320: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
e330: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
e340: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
e350: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
e360: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
e370: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
e380: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
e390: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
e3a0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
e3b0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
e3c0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
e3d0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
e3e0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
e3f0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
e400: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
e410: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
e420: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
e430: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
e440: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
e450: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
e460: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
e470: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
e480: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
e490: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
e4a0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
e4b0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
e4c0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
e4d0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
e4e0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
e4f0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
e500: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
e510: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
e520: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
e530: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
e540: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
e550: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
e560: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
e570: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
e580: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
e590: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
e5a0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
e5b0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
e5c0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
e5d0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
e5e0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
e5f0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
e600: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
e610: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
e620: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
e630: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
e640: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
e650: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
e660: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
e670: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
e680: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
e690: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
e6a0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
e6b0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
e6c0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
e6d0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
e6e0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
e6f0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
e700: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
e710: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
e720: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
e730: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
e740: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
e750: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
e760: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e770: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
e780: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
e790: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
e7a0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
e7b0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
e7c0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
e7d0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
e7e0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
e7f0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
e800: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
e810: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
e820: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
e830: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
e840: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
e850: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
e860: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
e870: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
e880: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
e890: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
e8a0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
e8b0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
e8c0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
e8d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e8e0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e8f0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e900: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e910: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e920: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e930: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e940: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e950: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e960: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e970: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e980: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e990: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e9a0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e9b0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e9c0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
e9d0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e9e0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e9f0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
ea00: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
ea10: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
ea20: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
ea30: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
ea40: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
ea50: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
ea60: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
ea70: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
ea80: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ea90: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
eaa0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
eab0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
eac0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
ead0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
eae0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
eaf0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
eb00: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
eb10: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
eb20: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
eb30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
eb40: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
eb50: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
eb60: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
eb70: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
eb80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eb90: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
eba0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
ebb0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
ebc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ebd0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
ebe0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
ebf0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
ec00: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
ec10: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
ec20: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
ec30: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
ec40: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
ec50: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
ec60: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
ec70: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
ec80: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
ec90: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
eca0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
ecb0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
ecc0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
ecd0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
ece0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
ecf0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
ed00: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
ed10: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
ed20: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
ed30: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
ed40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ed50: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
ed60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ed70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ed80: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
ed90: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
eda0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
edb0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
edc0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
edd0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
ede0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
edf0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
ee00: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
ee10: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
ee20: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
ee30: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ee40: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
ee50: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
ee60: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
ee70: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
ee80: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
ee90: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
eea0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
eeb0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
eec0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
eed0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
eee0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
eef0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
ef00: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
ef10: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
ef20: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ef30: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ef40: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
ef50: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
ef60: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
ef70: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ef80: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
ef90: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
efa0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
efb0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
efc0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
efd0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
efe0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
eff0: 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72  ppended in futur
f000: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
f010: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
f020: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
f030: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
f040: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
f050: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
f060: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
f070: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
f080: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
f090: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
f0a0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
f0b0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
f0c0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
f0d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
f0e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
f0f0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
f100: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
f110: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
f120: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
f130: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
f140: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
f150: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f160: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
f170: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
f180: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
f190: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
f1a0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
f1b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f1c0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
f1d0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
f1e0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f1f0: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
f200: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
f210: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
f220: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
f230: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
f240: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
f250: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
f260: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
f270: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
f280: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f290: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
f2a0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
f2b0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
f2c0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
f2d0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
f2e0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
f2f0: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
f300: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
f310: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
f320: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f330: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
f340: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
f350: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f360: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
f370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
f380: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
f390: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
f3a0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
f3b0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
f3c0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
f3d0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
f3e0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
f3f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
f400: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
f410: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f420: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
f430: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
f440: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
f450: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
f460: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f470: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
f480: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
f490: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
f4a0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
f4b0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
f4c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
f4d0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
f4e0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
f4f0: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
f500: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
f510: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
f520: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
f530: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
f540: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
f550: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
f560: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
f570: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
f580: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
f590: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
f5a0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
f5b0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
f5c0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
f5d0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
f5e0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
f5f0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
f600: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
f610: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f620: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
f630: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f640: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f650: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
f660: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
f670: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
f680: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
f690: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
f6a0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
f6b0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
f6c0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
f6d0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
f6e0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f6f0: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
f700: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
f710: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
f720: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
f730: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
f740: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
f750: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
f760: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
f770: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
f780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f790: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
f7a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f7b0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
f7c0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
f7d0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
f7e0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
f7f0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f800: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
f810: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
f820: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
f830: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f840: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
f850: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f860: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
f870: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
f880: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
f890: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
f8a0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
f8b0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
f8c0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
f8d0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
f8e0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f8f0: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f900: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f910: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f920: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f930: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f940: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f950: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f960: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f970: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f980: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f990: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f9a0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f9b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f9c0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
f9d0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f9e0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f9f0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
fa00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fa10: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
fa20: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
fa30: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
fa40: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
fa50: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
fa60: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
fa70: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
fa80: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
fa90: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
faa0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
fab0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
fac0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
fad0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
fae0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
faf0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fb00: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
fb10: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
fb20: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
fb30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb40: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
fb50: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
fb60: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
fb70: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
fb80: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
fb90: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
fba0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
fbb0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
fbc0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
fbd0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
fbe0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
fbf0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
fc00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fc10: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
fc20: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
fc30: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
fc40: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
fc50: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
fc60: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fc70: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
fc80: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
fc90: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
fca0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
fcb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fcc0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
fcd0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fce0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
fcf0: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
fd00: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fd10: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
fd20: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
fd30: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
fd40: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
fd50: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fd60: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
fd70: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
fd80: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
fd90: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
fda0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
fdb0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
fdc0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
fdd0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
fde0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
fdf0: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
fe00: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
fe10: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
fe20: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
fe30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fe40: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
fe50: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
fe60: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
fe70: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
fe80: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
fe90: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
fea0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
feb0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
fec0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
fed0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fee0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
fef0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
ff00: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
ff10: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
ff20: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
ff30: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
ff40: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
ff50: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ff60: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
ff70: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
ff80: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
ff90: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
ffa0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
ffb0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
ffc0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
ffd0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
ffe0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
fff0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
10000 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
10010 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
10020 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
10030 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
10040 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
10050 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
10060 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
10070 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
10080 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
10090 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
100a0 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
100b0 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
100c0 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
100d0 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
100e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
100f0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
10100 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
10110 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
10120 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
10130 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
10140 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10150 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
10160 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
10170 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
10180 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
10190 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
101a0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
101b0 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
101c0 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
101d0 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
101e0 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
101f0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
10200 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
10210 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
10220 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
10230 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
10240 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
10250 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10260 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
10270 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
10280 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
10290 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
102a0 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
102b0 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
102c0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
102d0 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
102e0 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
102f0 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
10300 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
10310 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
10320 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
10330 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
10340 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
10350 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
10360 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10370 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
10380 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
10390 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
103a0 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
103b0 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
103c0 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
103d0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
103e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
103f0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
10400 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
10410 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
10420 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
10430 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
10440 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
10450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
10460 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
10470 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
10480 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
10490 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
104a0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
104b0 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
104c0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
104d0 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
104e0 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
104f0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
10500 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
10510 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
10520 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
10530 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
10540 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
10550 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
10560 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
10570 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
10580 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
10590 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
105a0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
105b0 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
105c0 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
105d0 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
105e0 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
105f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
10600 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
10610 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
10620 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
10630 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10640 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
10650 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
10660 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
10670 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
10680 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
10690 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
106a0 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
106b0 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
106c0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
106d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
106e0 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
106f0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
10700 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
10710 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10720 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
10730 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10740 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
10750 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10760 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
10770 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
10780 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10790 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
107a0 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
107b0 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
107c0 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
107d0 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
107e0 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
107f0 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
10800 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
10810 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
10820 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
10830 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
10840 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
10850 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
10860 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
10870 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
10880 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
10890 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
108a0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
108b0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
108c0 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
108d0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
108e0 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
108f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10900 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
10910 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10920 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
10930 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10940 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10950 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10960 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
10970 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
10980 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
10990 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
109a0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
109b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
109c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
109d0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
109e0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
109f0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10a00 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10a10 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10a20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
10a30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10a40 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10a50 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
10a60 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
10a70 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
10a80 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
10a90 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
10aa0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
10ab0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
10ac0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
10ad0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
10ae0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
10af0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10b00 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
10b10 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
10b20 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
10b30 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10b40 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10b50 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
10b60 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
10b70 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
10b80 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
10b90 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
10ba0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
10bb0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
10bc0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
10bd0 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
10be0 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
10bf0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10c00 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
10c10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10c20 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10c30 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
10c40 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
10c50 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
10c60 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
10c70 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
10c80 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
10c90 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
10ca0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10cb0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
10cc0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
10cd0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
10ce0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10cf0 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
10d00 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10d10 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
10d20 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
10d30 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
10d40 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
10d50 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
10d60 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
10d70 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
10d80 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
10d90 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
10da0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
10db0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
10dc0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
10dd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10de0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10df0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
10e00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10e10 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
10e20 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
10e30 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
10e40 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
10e50 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
10e60 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
10e70 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
10e80 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
10e90 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
10ea0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10eb0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
10ec0 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
10ed0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
10ee0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10ef0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10f00 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
10f10 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
10f20 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
10f30 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
10f40 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
10f50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
10f60 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
10f70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
10f80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
10f90 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
10fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10fb0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
10fc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
10fd0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
10fe0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
10ff0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11000 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
11010 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
11020 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
11030 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
11040 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
11050 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
11060 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
11070 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11080 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
11090 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
110a0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
110b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
110c0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
110d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
110e0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
110f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11100 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
11110 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
11120 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
11130 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11140 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
11150 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
11160 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
11170 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
11180 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
11190 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
111a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
111b0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
111c0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
111d0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
111e0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
111f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
11200 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
11210 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
11220 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
11230 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
11240 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
11250 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
11260 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
11270 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
11280 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
11290 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
112a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
112b0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
112c0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
112d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
112e0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
112f0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
11300 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
11310 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
11320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11330 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
11340 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
11350 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
11360 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
11370 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11380 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
11390 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
113a0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
113b0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
113c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
113d0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
113e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
113f0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
11400 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
11410 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
11420 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
11430 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
11440 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11450 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
11460 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
11470 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
11480 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11490 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
114a0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
114b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
114c0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
114d0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
114e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
114f0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
11500 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
11510 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
11520 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
11530 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
11540 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
11550 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
11560 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
11570 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
11580 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
11590 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
115a0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
115b0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
115c0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
115d0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
115e0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
115f0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
11600 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
11610 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
11620 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
11630 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
11640 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
11650 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
11660 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
11670 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
11680 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
11690 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
116a0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
116b0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
116c0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
116d0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
116e0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
116f0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
11700 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
11710 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
11720 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
11730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
11740 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
11750 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
11760 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
11770 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
11780 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
11790 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
117a0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
117b0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
117c0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
117d0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
117e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
117f0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
11800 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
11810 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
11820 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
11830 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
11840 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
11850 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11860 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
11870 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
11880 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
11890 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
118a0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
118b0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
118c0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
118d0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
118e0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
118f0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
11900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
11910 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
11920 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
11930 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11940 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
11950 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
11960 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
11970 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
11980 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
11990 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
119a0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
119b0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
119c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
119d0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
119e0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
119f0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
11a00 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
11a10 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
11a20 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
11a30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11a40 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
11a50 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
11a60 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
11a70 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
11a80 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
11a90 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
11aa0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
11ab0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
11ac0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
11ad0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
11ae0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
11af0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
11b00 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
11b10 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
11b20 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
11b30 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
11b40 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
11b50 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
11b60 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
11b70 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
11b80 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
11b90 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11ba0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
11bb0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
11bc0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11bd0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
11be0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
11bf0 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
11c00 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
11c10 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
11c20 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
11c30 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
11c40 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
11c50 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
11c60 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
11c70 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
11c80 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
11c90 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
11ca0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
11cb0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
11cc0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
11cd0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
11ce0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
11cf0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11d00 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
11d10 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
11d20 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
11d30 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
11d40 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
11d50 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
11d60 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
11d70 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
11d80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
11d90 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
11da0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
11db0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
11dc0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11dd0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11de0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
11df0 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
11e00 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
11e10 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
11e20 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11e30 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11e40 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11e60 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11e70 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11e80 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11e90 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11ea0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
11eb0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11ec0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11ed0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
11ee0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
11ef0 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11f00 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
11f10 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
11f20 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11f30 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11f40 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11f50 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11f60 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11f70 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.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 7b 0a 20 20 76 6f 69 64  methods {.  void
11fa0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
11fb0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11fc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11fd0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
11fe0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
11ff0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
12000 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
12010 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
12020 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
12030 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
12040 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
12050 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12060 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
12070 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
12080 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
12090 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
120a0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
120b0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
120c0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
120d0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
120e0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
120f0 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
12100 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
12110 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
12120 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12130 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
12140 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
12150 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
12160 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
12170 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
12180 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
12190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
121a0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
121b0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
121c0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
121d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
121e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
121f0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
12200 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
12210 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
12220 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
12230 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
12240 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
12250 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
12260 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
12270 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
12280 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
12290 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
122a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
122b0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
122c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
122d0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
122e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
122f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
12300 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
12310 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
12320 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
12330 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
12340 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
12350 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
12360 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
12370 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
12380 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
12390 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
123a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
123b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
123c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
123d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
123e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
123f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
12400 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
12410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
12420 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
12430 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
12440 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12450 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
12460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12470 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
12480 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12490 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
124a0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
124b0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
124c0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
124d0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
124e0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
124f0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
12500 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
12510 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
12520 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
12530 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
12540 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
12550 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
12560 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
12570 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12580 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12590 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
125a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
125b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
125c0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
125d0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
125e0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
125f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12600 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
12610 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
12620 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
12630 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12640 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12650 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
12660 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12670 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12680 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12690 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
126a0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
126b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
126c0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
126d0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
126e0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
126f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12700 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12710 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12720 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12730 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12740 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12750 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
12760 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
12770 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
12780 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
12790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
127a0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
127b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
127c0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
127d0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
127e0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
127f0 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
12800 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12810 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12830 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
12840 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
12850 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
12860 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
12870 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
12880 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
12890 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
128a0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
128b0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
128c0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
128d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
128e0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
128f0 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
12900 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12910 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12920 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12930 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12940 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12950 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12960 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12970 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
12980 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
12990 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
129a0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
129b0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
129c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
129d0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
129e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
129f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12a00 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
12a10 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12a20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12a30 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12a40 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12a50 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12a60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
12a70 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
12a80 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12a90 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
12aa0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
12ab0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12ac0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
12ad0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
12ae0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
12af0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
12b00 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
12b10 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
12b20 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
12b30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12b40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12b50 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
12b60 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
12b70 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
12b80 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
12b90 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12ba0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
12bb0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
12bc0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12bd0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
12be0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
12bf0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
12c00 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12c10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12c20 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
12c30 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
12c40 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
12c50 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
12c60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
12c70 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
12c80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12c90 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
12ca0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
12cb0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
12cc0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12cd0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12ce0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12cf0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12d00 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12d10 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12d20 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12d30 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12d40 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
12d50 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
12d60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12d70 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
12d80 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12d90 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
12da0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
12db0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12dc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12dd0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12de0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12df0 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
12e00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12e10 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12e20 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12e30 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12e40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12e50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12e60 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
12e70 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12e80 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12e90 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12ea0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
12eb0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12ec0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12ed0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
12ee0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12ef0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12f00 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12f10 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12f20 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12f30 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12f40 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12f50 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12f60 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12f70 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12f80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12f90 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12fa0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
12fb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12fc0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
12fd0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12ff0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
13000 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13010 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
13020 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13030 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
13040 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13050 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13060 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
13070 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
13080 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
13090 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
130a0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
130b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
130c0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
130d0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
130e0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
130f0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
13100 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13110 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
13120 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
13130 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
13140 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
13150 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13160 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
13170 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
13180 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
13190 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
131a0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
131b0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
131c0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
131d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
131e0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
131f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13200 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
13210 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13220 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13230 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
13240 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
13250 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
13260 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
13270 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
13280 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
13290 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
132a0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
132b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
132c0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
132d0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
132e0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
132f0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
13300 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
13310 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13320 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
13330 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
13340 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
13350 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
13360 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
13370 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
13380 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
13390 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
133a0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
133b0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
133c0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
133d0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
133e0 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
133f0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13400 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
13410 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
13420 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
13430 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
13440 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
13450 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
13460 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
13470 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
13480 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
13490 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
134a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
134b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
134c0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
134d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
134e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
134f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13500 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
13510 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13520 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13530 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13540 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
13550 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
13560 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13570 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
13580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
13590 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
135a0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
135b0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
135c0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
135d0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
135e0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
135f0 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
13600 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
13610 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
13620 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
13630 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
13640 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13650 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
13660 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13670 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
13680 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
13690 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
136a0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
136b0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
136c0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
136d0 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
136e0 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
136f0 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
13700 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
13710 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
13720 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
13730 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
13740 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
13750 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
13760 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
13770 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
13780 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
13790 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
137a0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
137b0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
137c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
137d0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
137e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
137f0 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
13800 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
13810 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
13820 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
13830 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
13840 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
13850 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
13860 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
13870 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
13880 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
13890 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
138a0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
138b0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
138c0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
138d0 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
138e0 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
138f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13900 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
13910 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
13920 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
13930 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
13940 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
13950 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13960 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
13970 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13980 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
13990 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
139a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
139b0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
139c0 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20  cifies a memory 
139d0 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c  pool.** that SQL
139e0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
139f0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
13a00 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
13a10 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a   default page.**
13a20 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13a30 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
13a40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13a50 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70  ption is a no-op
13a60 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
13a70 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
13a80 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
13a90 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
13aa0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
13ab0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13ac0 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  2]..** ^There ar
13ad0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13ae0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
13af0 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
13b00 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
13b10 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d  byte aligned mem
13b20 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20  ory (pMem), the 
13b30 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
13b40 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a  e cache line (sz
13b50 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75  ),.** and the nu
13b60 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69  mber of cache li
13b70 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  nes (N)..** The 
13b80 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
13b90 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
13ba0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
13bb0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
13bc0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
13bd0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36  etween 512 and 6
13be0 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20  5536) plus some 
13bf0 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20  extra bytes for 
13c00 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
13c10 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65  der.  ^The numbe
13c20 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73  r of extra bytes
13c30 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70   needed by the p
13c40 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61  age header.** ca
13c50 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
13c60 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f  using [SQLITE_CO
13c70 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
13c80 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  Z]..** ^It is ha
13c90 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
13ca0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
13cb0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
13cc0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
13cd0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
13ce0 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
13cf0 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  pMem.** argument
13d00 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
13d10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
13d20 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  r a pointer to a
13d30 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
13d40 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  ned block of mem
13d50 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
13d60 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65  sz*N bytes, othe
13d70 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75  rwise.** subsequ
13d80 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ent behavior is 
13d90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57  undefined..** ^W
13da0 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20  hen pMem is not 
13db0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
13dc0 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20  l strive to use 
13dd0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
13de0 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66  ded.** to satisf
13df0 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65  y page cache nee
13e00 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b  ds, falling back
13e10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13e20 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70  loc()] if.** a p
13e30 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69  age cache line i
13e40 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a  s larger than sz
13e50 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c   bytes or if all
13e60 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66   of the pMem buf
13e70 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73  fer.** is exhaus
13e80 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d  ted..** ^If pMem
13e90 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69   is NULL and N i
13ea0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
13eb0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
13ec0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65  onnection.** doe
13ed0 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c  s an initial bul
13ee0 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  k allocation for
13ef0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13f00 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ry.** from [sqli
13f10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75  te3_malloc()] su
13f20 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63  fficient for N c
13f30 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20  ache lines if N 
13f40 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a  is positive or.*
13f50 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74  * of -1024*N byt
13f60 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  es if N is negat
13f70 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74  ive, . ^If addit
13f80 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
13f90 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
13fa0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
13fb0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
13fc0 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61  the initial.** a
13fd0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
13fe0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
13ff0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14000 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72  ] separately for
14010 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f   each.** additio
14020 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20  nal cache line. 
14030 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14050 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14060 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
14070 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
14080 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
14090 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
140a0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
140b0 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20  buffer .** that 
140c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
140d0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
140e0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
140f0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a  location needs.*
14100 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  * beyond those p
14110 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b  rovided for by [
14120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14130 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53  RATCH] and.** [S
14140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
14150 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65  ECACHE]..** ^The
14160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14170 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  EAP option is on
14180 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
14190 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
141a0 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65  ed.** with eithe
141b0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
141c0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51  _MEMSYS3] or [SQ
141d0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
141e0 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73  YS5] and returns
141f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
14200 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74  R] if invoked ot
14210 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65  herwise..** ^The
14220 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
14230 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
14240 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a  _CONFIG_HEAP:.**
14250 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
14260 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
14270 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
14280 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
14290 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
142a0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
142b0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
142c0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
142d0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
142e0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
142f0 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
14300 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
14310 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
14320 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
14330 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
14340 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
14350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
14360 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
14370 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
14380 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
14390 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
143a0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
143b0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
143c0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ULL then the alt
143d0 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
143e0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
143f0 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
14400 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
14410 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14420 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
14430 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
14440 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
14450 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
14460 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
14470 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
14480 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
14490 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
144a0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
144b0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
144c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
144d0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
144e0 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
144f0 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
14500 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14510 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
14520 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
14530 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14540 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14550 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14560 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
14570 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14590 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
145a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
145b0 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70   which is a.** p
145c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
145d0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
145e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
145f0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14600 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
14610 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e  specifies altern
14620 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
14630 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
14640 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20  o be used.** in 
14650 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20  place the mutex 
14660 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
14670 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
14680 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14690 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
146a0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
146b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
146c0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
146d0 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
146e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
146f0 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
14700 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14710 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14720 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14730 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14740 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14750 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14760 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
14770 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
14780 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
14790 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
147a0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
147b0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
147c0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
147d0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
147e0 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
147f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14800 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14810 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14820 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14830 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
14840 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14850 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
14860 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14870 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14880 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  TMUTEX option ta
14890 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
148a0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
148b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
148c0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
148d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
148e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
148f0 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
14900 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14910 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
14920 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
14930 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
14940 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
14950 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
14960 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
14970 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
14980 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
14990 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
149a0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
149b0 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
149c0 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
149d0 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
149e0 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
149f0 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
14a00 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
14a10 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14a20 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
14a30 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
14a40 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
14a50 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14a60 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14a70 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
14a80 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
14a90 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
14aa0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
14ab0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
14ac0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14ad0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
14ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14af0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
14b00 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
14b10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14b20 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
14b30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14b40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
14b50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14b60 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
14b70 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14b90 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b  ASIDE option tak
14ba0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14bb0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a   that determine.
14bc0 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ** the default s
14bd0 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ize of lookaside
14be0 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20   memory on each 
14bf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14c00 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
14c10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
14c20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
14c30 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
14c40 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
14c50 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
14c60 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
14c70 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
14c80 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
14c90 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53  nnection.)^  ^(S
14ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14cb0 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74  KASIDE.** sets t
14cc0 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  he <i>default</i
14cd0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
14ce0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
14cf0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14d00 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b  ].** option to [
14d10 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14d20 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
14d30 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
14d40 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
14d50 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
14d60 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
14d70 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
14d80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14d90 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
14da0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
14db0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
14dc0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14dd0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
14de0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14df0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14e00 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
14e10 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14e20 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14e30 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
14e40 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
14e50 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65  fies.** the inte
14e60 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f  rface to a custo
14e70 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
14e80 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a  lementation.)^.*
14e90 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  * ^SQLite makes 
14ea0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
14eb0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14ec0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c  thods2] object.<
14ed0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14ee0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14ef0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14f00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14f10 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14f20 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14f30 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14f40 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14f50 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14f60 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
14f70 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14f80 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14f90 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
14fa0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a  QLite copies of.
14fb0 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70  ** the current p
14fc0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14fd0 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
14fe0 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
14ff0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15000 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
15010 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15020 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
15030 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
15040 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
15050 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
15060 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
15070 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
15080 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
15090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
150a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
150b0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
150c0 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
150d0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
150e0 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
150f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
15100 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
15110 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
15120 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
15130 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
15140 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
15150 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
15160 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
15170 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
15180 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
15190 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
151a0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
151b0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
151c0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
151d0 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
151e0 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
151f0 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
15200 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
15210 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
15220 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15230 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
15240 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
15250 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15260 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
15270 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
15280 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
15290 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
152a0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
152b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
152c0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
152d0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
152e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
152f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15300 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
15310 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
15320 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
15330 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
15340 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
15350 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
15360 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
15370 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
15380 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
15390 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
153a0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
153b0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
153c0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
153d0 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
153e0 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
153f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
15400 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
15410 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
15420 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
15430 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
15440 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
15450 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
15460 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
15470 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
15480 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
15490 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
154a0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
154b0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
154c0 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
154d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
154e0 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
154f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15500 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
15520 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15530 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
15540 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49  f type int..** I
15550 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
15560 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
15570 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
15580 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
15590 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20  ter is zero,.** 
155a0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
155b0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  g is globally di
155c0 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
155d0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
155e0 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65  obally.** enable
155f0 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
15600 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
15610 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
15620 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
15630 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
15640 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
15650 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
15660 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
15670 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
15680 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
15690 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
156a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
156b0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
156c0 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
156d0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
156e0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
156f0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
15700 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
15710 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
15720 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
15730 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
15740 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
15750 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
15760 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
15770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15780 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
15790 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
157a0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
157b0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
157c0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
157d0 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
157e0 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
157f0 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
15800 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
15810 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
15820 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15830 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
15840 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
15850 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
15860 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15870 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  AN.** <dd>^The S
15880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15890 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
158a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
158b0 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a  single integer.*
158c0 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  * argument which
158d0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
158e0 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  as a boolean in 
158f0 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
15900 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  or disable.** th
15910 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
15920 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
15930 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
15940 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
15950 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64  mizer..** ^The d
15960 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
15970 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
15980 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
15990 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
159a0 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
159b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
159c0 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
159d0 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
159e0 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
159f0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
15a00 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
15a10 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15a20 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15a30 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
15a40 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
15a50 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
15a60 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
15a70 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
15a80 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68  alfunction.** wh
15a90 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
15aa0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
15ab0 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
15ac0 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
15ad0 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
15ae0 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
15af0 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
15b00 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
15b10 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
15b20 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
15b30 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
15b40 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
15b50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15b60 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
15b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15b80 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
15b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15ba0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
15bb0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
15bc0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
15bd0 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
15be0 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
15bf0 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
15c00 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
15c10 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
15c20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15c30 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
15c40 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
15c50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15c60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
15c70 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
15c80 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
15c90 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
15ca0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
15cb0 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
15cc0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
15cd0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
15ce0 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
15cf0 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
15d00 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
15d10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
15d20 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
15d30 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
15d40 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
15d50 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
15d60 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
15d70 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
15d80 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
15d90 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
15da0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
15db0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
15dc0 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
15dd0 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
15de0 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
15df0 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
15e00 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
15e10 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
15e20 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
15e30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
15e40 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
15e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
15e60 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
15e70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15e80 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
15e90 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
15ea0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
15eb0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
15ec0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
15ed0 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
15ee0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
15ef0 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15f00 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
15f10 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
15f20 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
15f30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
15f40 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
15f50 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
15f60 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
15f70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15f80 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
15f90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
15fa0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
15fb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15fc0 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
15fd0 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
15fe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
15ff0 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
16000 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
16010 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
16020 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16030 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
16040 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
16050 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
16060 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
16070 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
16080 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
16090 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
160a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
160b0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
160c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
160d0 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51  _SIZE.** <dd>^SQ
160e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
160f0 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
16100 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
16110 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
16120 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
16130 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
16140 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
16150 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
16160 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
16170 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
16180 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
16190 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
161a0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64  limit..** ^The d
161b0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63  efault setting c
161c0 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
161d0 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73   by each databas
161e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
161f0 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65  ng.** either the
16200 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
16210 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20  ze] command, or 
16220 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  by using the.** 
16230 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
16240 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
16250 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61  ntrol.  ^(The ma
16260 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
16270 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20  ap size.** will 
16280 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  be silently trun
16290 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61  cated if necessa
162a0 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f  ry so that it do
162b0 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68  es not exceed th
162c0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  e.** compile-tim
162d0 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73  e maximum mmap s
162e0 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a  ize set by the.*
162f0 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d  * [SQLITE_MAX_MM
16300 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65  AP_SIZE] compile
16310 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a  -time option.)^.
16320 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72  ** ^If either ar
16330 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f  gument to this o
16340 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76  ption is negativ
16350 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67  e, then that arg
16360 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e  ument is.** chan
16370 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69  ged to its compi
16380 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e  le-time default.
16390 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
163a0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
163b0 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PSIZE]].** <dt>S
163c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
163d0 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c  32_HEAPSIZE.** <
163e0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
163f0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16400 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f  SIZE option is o
16410 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
16420 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
16430 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f  mpiled for Windo
16440 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ws with the [SQL
16450 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
16460 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
16470 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64  macro.** defined
16480 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  . ^SQLITE_CONFIG
16490 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
164a0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
164b0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
164c0 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
164d0 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
164e0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
164f0 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
16500 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16510 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
16520 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16530 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16540 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
16550 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16560 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
16570 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16580 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16590 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
165a0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
165b0 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
165c0 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
165d0 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
165e0 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
165f0 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
16600 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16620 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61  CACHE]..** The a
16630 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73  mount of extra s
16640 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
16650 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
16660 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
16670 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
16680 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
16690 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  te version..**.*
166a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
166b0 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  G_PMASZ]].** <dt
166c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
166d0 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  MASZ.** <dd>^The
166e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
166f0 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  MASZ option take
16700 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16710 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16720 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   an unsigned int
16730 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68  eger and sets th
16740 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  e "Minimum PMA S
16750 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c  ize" for the mul
16760 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f  tithreaded.** so
16770 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74  rter to that int
16780 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  eger.  The defau
16790 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  lt minimum PMA S
167a0 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68  ize is set by th
167b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52  e.** [SQLITE_SOR
167c0 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69  TER_PMASZ] compi
167d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
167e0 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65   New threads are
167f0 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20   launched.** to 
16800 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f  help with sort o
16810 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d  perations when m
16820 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72  ultithreaded sor
16830 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c  ting.** is enabl
16840 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50  ed (using the [P
16850 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63  RAGMA threads] c
16860 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20  ommand) and the 
16870 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e  amount of conten
16880 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65  t.** to be sorte
16890 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61  d exceeds the pa
168a0 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68  ge size times th
168b0 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65  e minimum of the
168c0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68  .** [PRAGMA cach
168d0 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20  e_size] setting 
168e0 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a  and this value..
168f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16900 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16910 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  PILL]].** <dt>SQ
16920 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16930 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64  JRNL_SPILL.** <d
16940 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16950 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
16960 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ILL option takes
16970 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
16980 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63  ter which.** bec
16990 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d  omes the [statem
169a0 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69  ent journal] spi
169b0 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73  ll-to-disk thres
169c0 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74  hold.  .** [Stat
169d0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20  ement journals] 
169e0 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f  are held in memo
169f0 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73  ry until their s
16a00 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a  ize (in bytes).*
16a10 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74  * exceeds this t
16a20 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69  hreshold, at whi
16a30 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72  ch point they ar
16a40 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  e written to dis
16a50 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20  k..** Or if the 
16a60 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c  threshold is -1,
16a70 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
16a80 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68  als are always h
16a90 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65  eld.** exclusive
16aa0 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ly in memory..**
16ab0 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74   Since many stat
16ac0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e  ement journals n
16ad0 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67  ever become larg
16ae0 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73  e, setting the s
16af0 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c  pill.** threshol
16b00 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63  d to a value suc
16b10 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67  h as 64KiB can g
16b20 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68  reatly reduce th
16b30 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49  e amount of.** I
16b40 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73  /O required to s
16b50 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74  upport statement
16b60 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   rollback..** Th
16b70 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
16b80 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67  for this setting
16b90 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62   is controlled b
16ba0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16bb0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
16bc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16bd0 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  tion..** </dl>.*
16be0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16bf0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
16c00 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
16c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16c20 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
16c30 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
16c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16c50 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
16c60 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
16c70 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
16c80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
16c90 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
16ca0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16cb0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16cd0 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
16ce0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
16cf0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
16d00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16d10 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
16d20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
16d30 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16d40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16d50 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
16d60 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
16d70 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
16d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d90 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
16da0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
16db0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
16dc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16dd0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
16de0 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
16df0 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
16e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16e10 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
16e20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
16e30 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16e50 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
16e60 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
16e70 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
16e80 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
16e90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
16ea0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
16eb0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
16ec0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
16ed0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16ee0 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
16ef0 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
16f00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16f10 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
16f20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16f30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16f40 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
16f50 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
16f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f70 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
16f80 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
16f90 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
16fa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
16fb0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
16fc0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
16fd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16fe0 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
16ff0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
17000 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
17010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17020 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
17030 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
17040 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17050 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17060 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
17070 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
17080 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
17090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
170a0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
170b0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
170c0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
170d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
170e0 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
170f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
17100 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
17110 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17120 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17130 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
17140 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
17150 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17160 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17170 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
17180 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
17190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
171a0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
171b0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
171c0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
171d0 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ma */.#define SQ
171e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
171f0 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20  JRNL_SPILL      
17200 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  26  /* int nByte
17210 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
17220 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
17230 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
17240 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
17250 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
17260 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
17270 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
17280 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17290 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
172a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
172b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
172c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
172d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
172e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
172f0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
17300 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
17310 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
17320 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
17330 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
17340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17350 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
17360 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
17370 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
17380 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
17390 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
173a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
173b0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
173c0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
173d0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
173e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
173f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
17400 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
17410 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
17420 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
17430 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
17440 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
17450 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
17460 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
17470 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
17480 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17490 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
174a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
174b0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
174c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
174d0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
174e0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
174f0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
17500 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
17510 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
17520 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17530 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
17540 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
17550 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17560 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
17570 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
17580 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
17590 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
175a0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
175b0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
175c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
175d0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
175e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
175f0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
17600 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
17610 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
17620 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
17630 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
17640 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
17650 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
17660 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
17670 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
17680 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
17690 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
176a0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
176b0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
176c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
176d0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
176e0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
176f0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
17700 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
17710 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
17720 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
17730 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
17740 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
17750 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
17760 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
17770 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
17780 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
17790 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
177a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
177b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
177c0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
177d0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
177e0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
177f0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
17800 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
17810 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
17820 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
17830 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
17840 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17850 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
17860 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
17870 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
17880 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
17890 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
178a0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
178b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
178c0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
178d0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
178e0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
178f0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
17900 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
17910 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
17920 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
17930 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
17940 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
17950 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
17960 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
17970 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
17980 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
17990 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
179a0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
179b0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
179c0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
179d0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
179e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
179f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17a00 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
17a10 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17a20 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17a30 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17a40 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
17a50 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
17a60 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
17a70 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17a80 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17a90 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17aa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17ab0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17ac0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17ad0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
17ae0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
17af0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
17b00 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
17b10 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
17b20 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
17b30 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
17b40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17b50 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17b60 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17b70 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17b80 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17b90 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17ba0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
17bb0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
17bc0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17bd0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17be0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17bf0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17c00 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17c10 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
17c20 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
17c30 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17c40 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17c50 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17c60 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
17c70 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
17c80 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17c90 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17ca0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
17cb0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
17cc0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
17cd0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17ce0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17cf0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17d00 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17d10 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17d20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
17d30 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
17d40 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
17d50 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
17d60 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
17d70 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
17d80 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
17d90 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
17da0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17db0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
17dc0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17dd0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17de0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
17df0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
17e00 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
17e10 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17e20 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17e30 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17e40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17e50 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17e60 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
17e70 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17e80 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17e90 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17ea0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17eb0 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c  _FTS3_TOKENIZER<
17ec0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17ed0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
17ee0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17ef0 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61  isable the two-a
17f00 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69  rgument.** versi
17f10 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f  on of the [fts3_
17f20 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e  tokenizer()] fun
17f30 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70  ction which is p
17f40 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46  art of the.** [F
17f50 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73  TS3] full-text s
17f60 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74  earch engine ext
17f70 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  ension..** There
17f80 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
17f90 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17fa0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
17fb0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17fc0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17fd0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66  s 0 to disable f
17fe0 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
17ff0 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  or.** positive t
18000 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f  o enable fts3_to
18010 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67  kenizer() or neg
18020 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
18030 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e  he setting.** un
18040 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
18050 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18060 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18070 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
18080 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
18090 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
180a0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
180b0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69  fts3_tokenizer i
180c0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
180d0 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
180e0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
180f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18100 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
18110 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
18120 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18130 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
18140 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18150 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
18160 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18170 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
18180 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20  TENSION</dt>.** 
18190 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
181a0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
181b0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
181c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
181d0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a  _extension()].**
181e0 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70   interface indep
181f0 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20  endently of the 
18200 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
18210 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  )] SQL function.
18220 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
18230 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
18240 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e  ension()] API en
18250 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
18260 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d  s both the.** C-
18270 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  API [sqlite3_loa
18280 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61  d_extension()] a
18290 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
182a0 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73  ion [load_extens
182b0 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65  ion()]..** There
182c0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
182d0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
182e0 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65  nts..** When the
182f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18300 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  to this interfac
18310 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c  e is 1, then onl
18320 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a  y the C-API is.*
18330 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68  * enabled and th
18340 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
18350 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e  emains disabled.
18360 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61    If the first a
18370 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
18380 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18390 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65  0, then both the
183a0 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53   C-API and the S
183b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  QL function are 
183c0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20  disabled..** If 
183d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
183e0 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e  nt is -1, then n
183f0 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61  o changes are ma
18400 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65  de to state of e
18410 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41  ither the.** C-A
18420 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75  PI or the SQL fu
18430 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73  nction..** The s
18440 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18450 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18460 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18470 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18480 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18490 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b  dicate whether [
184a0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
184b0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
184c0 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c  ace.** is disabl
184d0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f  ed or enabled fo
184e0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
184f0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18500 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20  arameter may.** 
18510 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
18520 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  r, in which case
18530 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67   the new setting
18540 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
18550 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   back..** </dd>.
18560 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18570 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
18580 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NAME</dt>.** <dd
18590 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
185a0 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  s used to change
185b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
185c0 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65   "main" database
185d0 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68  .** schema.  ^Th
185e0 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20  e sole argument 
185f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18600 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20  a constant UTF8 
18610 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20  string.** which 
18620 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
18630 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  new schema name 
18640 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69  in place of "mai
18650 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  n".  ^SQLite.** 
18660 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20  does not make a 
18670 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20  copy of the new 
18680 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65  main schema name
18690 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20   string, so the 
186a0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
186b0 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
186c0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73  the argument pas
186d0 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42  sed into this DB
186e0 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73  CONFIG option is
186f0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e   unchanged.** un
18700 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61  til after the da
18710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18720 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64  n closes..** </d
18730 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18740 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
18750 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64  CKPT_ON_CLOSE</d
18760 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c  t>.** <dd> Usual
18770 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62  ly, when a datab
18780 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20  ase in wal mode 
18790 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74  is closed or det
187a0 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a  ached from a .**
187b0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
187c0 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20  , SQLite checks 
187d0 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61  if this will mea
187e0 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65  n that there are
187f0 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e   now no .** conn
18800 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74  ections at all t
18810 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  o the database. 
18820 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72  If so, it perfor
18830 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20  ms a checkpoint 
18840 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65  .** operation be
18850 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65  fore closing the
18860 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69   connection. Thi
18870 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20  s option may be 
18880 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72  used to.** overr
18890 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f  ide this behavio
188a0 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61  ur. The first pa
188b0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
188c0 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e  o this operation
188d0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
188e0 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20  r - non-zero to 
188f0 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69  disable checkpoi
18900 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72  nts-on-close, or
18910 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65   zero (the.** de
18920 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65  fault) to enable
18930 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e   them. The secon
18940 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18950 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18960 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77  nteger.** into w
18970 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20  hich is written 
18980 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18990 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b  te whether check
189a0 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a  points-on-close.
189b0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73  ** have been dis
189c0 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65  abled - 0 if the
189d0 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c  y are not disabl
189e0 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72  ed, 1 if they ar
189f0 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  e..** </dd>.**.*
18a00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18a10 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
18a20 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
18a30 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18a40 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70  G_ENABLE_QPSG op
18a50 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f  tion activates o
18a60 72 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a  r deactivates.**
18a70 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e   the [query plan
18a80 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20 67 75  ner stability gu
18a90 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e  arantee] (QPSG).
18aa0 20 20 57 68 65 6e 20 74 68 65 20 51 50 53 47 20    When the QPSG 
18ab0 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20  is active,.** a 
18ac0 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79  single SQL query
18ad0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
18ae0 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73  always use the s
18af0 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65  ame algorithm re
18b00 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76  gardless.** of v
18b10 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20  alues of [bound 
18b20 70 61 72 61 6d 65 74 65 72 73 5d 2e 20 20 54 68  parameters].  Th
18b30 65 20 51 50 53 47 20 64 69 73 61 62 6c 65 73 20  e QPSG disables 
18b40 73 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d  some query optim
18b50 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  izations.** that
18b60 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c   look at the val
18b70 75 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72  ues of bound par
18b80 61 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20 63  ameters, which c
18b90 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65  an make some que
18ba0 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20  ries.** slower. 
18bb0 20 42 75 74 20 74 68 65 20 51 50 53 47 20 68 61   But the QPSG ha
18bc0 73 20 74 68 65 20 61 64 76 61 6e 74 61 67 65 20  s the advantage 
18bd0 6f 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61  of more predicta
18be0 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57  ble behavior.  W
18bf0 69 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20  ith.** the QPSG 
18c00 61 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77  active, SQLite w
18c10 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74  ill always use t
18c20 68 65 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c  he same query pl
18c30 61 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20  an in the field 
18c40 61 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64  as.** was used d
18c50 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e  uring testing in
18c60 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 3c 2f 64   the lab..** </d
18c70 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
18c80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18c90 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
18ca0 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
18cb0 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68  1000 /* const ch
18cc0 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ar* */.#define S
18cd0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18ce0 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20  OOKASIDE        
18cf0 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69       1001 /* voi
18d00 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
18d10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18d20 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
18d30 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32  Y           1002
18d40 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18d60 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
18d70 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30  RIGGER        10
18d80 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  03 /* int int* *
18d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18da0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18db0 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20  _FTS3_TOKENIZER 
18dc0 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1004 /* int int*
18dd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18de0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18df0 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
18e00 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e  N 1005 /* int in
18e10 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18e20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
18e30 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20  _CKPT_ON_CLOSE  
18e40 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20      1006 /* int 
18e50 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18e60 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18e70 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20  ENABLE_QPSG     
18e80 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e        1007 /* in
18e90 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
18ea0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
18eb0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
18ec0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
18ed0 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
18ee0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
18ef0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
18f00 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
18f10 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
18f20 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
18f30 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
18f40 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
18f50 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
18f60 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
18f70 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
18f80 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
18f90 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
18fa0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
18fb0 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
18fc0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
18fd0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
18fe0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
18ff0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19000 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
19010 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
19020 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
19030 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
19040 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
19050 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
19060 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
19070 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
19080 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
19090 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
190a0 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
190b0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
190c0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
190d0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
190e0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
190f0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
19100 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
19110 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
19120 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
19130 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
19140 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
19150 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
19160 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
19170 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
19180 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
19190 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
191a0 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
191b0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
191c0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
191d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
191e0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
191f0 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
19200 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73   usually returns
19210 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a   the [rowid] of.
19220 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
19230 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
19240 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
19250 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
19260 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
19270 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
19280 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72  ection D. ^Inser
19290 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
192a0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
192b0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64  re not.** record
192c0 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  ed. ^If no succe
192d0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
192e0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
192f0 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
19300 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20  rred .** on the 
19310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19320 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69  ion D, then sqli
19330 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19340 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
19350 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a   .** zero..**.**
19360 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e   As well as bein
19370 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61  g set automatica
19380 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20  lly as rows are 
19390 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61  inserted into da
193a0 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73  tabase.** tables
193b0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
193c0 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
193d0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74  ction may be set
193e0 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a   explicitly by.*
193f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  * [sqlite3_set_l
19400 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19410 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76  ()].**.** Some v
19420 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
19430 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
19440 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74   INSERT rows int
19450 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61  o rowid tables a
19460 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d  s.** part of com
19470 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61  mitting a transa
19480 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66  ction (e.g. to f
19490 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75  lush data accumu
194a0 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  lated in memory.
194b0 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20  ** to disk). In 
194c0 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71  this case subseq
194d0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68  uent calls to th
194e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
194f0 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20  rn the rowid.** 
19500 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
19510 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49  these internal I
19520 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73  NSERT operations
19530 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f  , which leads to
19540 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65   .** unintuitive
19550 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61   results. Virtua
19560 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
19570 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20  tations that do 
19580 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a  write to rowid.*
19590 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73  * tables in this
195a0 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74   way can avoid t
195b0 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72  his problem by r
195c0 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69  estoring the ori
195d0 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20  ginal .** rowid 
195e0 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c  value using [sql
195f0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
19600 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65  sert_rowid()] be
19610 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a  fore returning .
19620 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68  ** control to th
19630 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e user..**.** ^(
19640 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
19650 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
19660 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73  rigger then this
19670 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a   routine will .*
19680 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  * return the [ro
19690 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
196a0 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67  rted row as long
196b0 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
196c0 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20  is .** running. 
196d0 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  Once the trigger
196e0 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74   program ends, t
196f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19700 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
19710 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
19720 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
19730 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
19740 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  was fired.)^.**.
19750 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
19760 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
19770 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
19780 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
19790 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
197a0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
197b0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
197c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
197d0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
197e0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
197f0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
19800 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
19810 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
19820 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
19830 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
19840 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
19850 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
19860 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
19870 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
19880 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
19890 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
198a0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
198b0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
198c0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
198d0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
198e0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
198f0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
19900 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
19910 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
19920 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
19930 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
19940 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
19950 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
19960 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
19970 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
19980 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
19990 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
199a0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
199b0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
199c0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
199d0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
199e0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
199f0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
19a00 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
19a10 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
19a20 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
19a30 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
19a40 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
19a50 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19a60 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
19a70 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
19a80 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
19a90 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
19aa0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
19ab0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
19ac0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
19ad0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
19ae0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
19af0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
19b00 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
19b10 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
19b20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
19b30 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
19b40 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
19b50 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19b60 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
19b70 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
19b80 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
19b90 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
19ba0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
19bb0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19bc0 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
19bd0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
19be0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19bf0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19c00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
19c10 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74   the Last Insert
19c20 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a   Rowid value..**
19c30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
19c40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
19c50 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
19c60 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d  rt_rowid(D, R) m
19c70 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65  ethod allows the
19c80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
19c90 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ** set the value
19ca0 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c   returned by cal
19cb0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73  ling sqlite3_las
19cc0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
19cd0 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f  ) to R .** witho
19ce0 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72  ut inserting a r
19cf0 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  ow into the data
19d00 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  base..*/.void sq
19d10 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
19d20 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
19d30 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  te3*,sqlite3_int
19d40 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
19d50 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
19d60 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
19d70 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
19d80 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19d90 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
19da0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
19db0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
19dc0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
19dd0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
19de0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
19df0 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
19e00 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
19e10 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
19e20 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
19e30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
19e40 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
19e50 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
19e60 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
19e70 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
19e80 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
19e90 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
19ea0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
19eb0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
19ec0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
19ed0 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
19ee0 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
19ef0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
19f00 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
19f10 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
19f20 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
19f30 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
19f40 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
19f50 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
19f60 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
19f70 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
19f80 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
19f90 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
19fa0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
19fb0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
19fc0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
19fd0 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
19fe0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
19ff0 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
1a000 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
1a010 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
1a020 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
1a030 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1a040 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
1a050 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
1a060 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
1a070 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
1a080 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
1a090 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
1a0a0 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
1a0b0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
1a0c0 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
1a0d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
1a0e0 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
1a0f0 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
1a100 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1a110 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
1a120 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
1a130 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
1a140 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
1a150 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
1a160 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
1a170 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
1a180 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
1a190 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
1a1a0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1a1b0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
1a1c0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1a1d0 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
1a1e0 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
1a1f0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
1a200 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
1a210 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1a220 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a230 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1a240 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a250 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
1a260 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
1a270 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1a280 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
1a290 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
1a2a0 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
1a2b0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
1a2c0 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
1a2d0 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
1a2e0 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
1a2f0 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
1a300 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
1a310 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
1a320 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a330 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1a340 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1a350 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
1a360 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
1a370 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
1a380 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
1a390 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
1a3a0 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
1a3b0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
1a3c0 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
1a3d0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1a3e0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
1a3f0 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
1a400 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
1a410 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
1a420 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
1a430 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
1a440 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
1a450 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
1a460 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
1a470 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
1a480 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
1a490 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1a4a0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1a4b0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1a4c0 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
1a4d0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
1a4e0 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
1a4f0 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
1a500 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
1a510 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
1a520 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1a530 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
1a540 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
1a550 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
1a560 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
1a570 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
1a580 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
1a590 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1a5a0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
1a5b0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
1a5c0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1a5d0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1a5e0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
1a5f0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
1a600 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
1a610 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1a620 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1a630 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1a640 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1a650 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1a660 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1a670 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1a680 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1a690 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1a6a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a6b0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1a6c0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a6d0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1a6e0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1a6f0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
1a700 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1a710 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1a720 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
1a730 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1a740 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a750 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
1a760 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1a770 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a780 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1a790 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1a7a0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
1a7b0 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
1a7c0 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
1a7d0 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
1a7e0 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
1a7f0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
1a800 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
1a810 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
1a820 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a830 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
1a840 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
1a850 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
1a860 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
1a870 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
1a880 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1a890 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1a8a0 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
1a8b0 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
1a8c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1a8d0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a8e0 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
1a8f0 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
1a900 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
1a910 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
1a920 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
1a930 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
1a940 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
1a950 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
1a960 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1a970 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
1a980 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1a990 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1a9a0 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
1a9b0 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
1a9c0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1a9d0 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
1a9e0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
1a9f0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1aa00 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1aa10 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1aa20 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
1aa30 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
1aa40 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1aa50 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1aa60 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1aa70 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1aa80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1aa90 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1aaa0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1aab0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1aac0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1aad0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
1aae0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1aaf0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1ab00 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1ab10 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1ab20 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1ab30 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
1ab40 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
1ab50 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
1ab60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1ab70 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1ab80 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
1ab90 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
1aba0 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
1abb0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
1abc0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
1abd0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
1abe0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
1abf0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
1ac00 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
1ac10 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
1ac20 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
1ac30 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
1ac40 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
1ac50 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
1ac60 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
1ac70 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
1ac80 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
1ac90 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
1aca0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1acb0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
1acc0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
1acd0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
1ace0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
1acf0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
1ad00 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
1ad10 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
1ad20 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1ad30 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
1ad40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ad50 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
1ad60 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
1ad70 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
1ad80 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1ad90 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
1ada0 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
1adb0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
1adc0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
1add0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
1ade0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
1adf0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
1ae00 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
1ae10 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
1ae20 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
1ae30 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
1ae40 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
1ae50 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
1ae60 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
1ae70 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
1ae80 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
1ae90 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
1aea0 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
1aeb0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
1aec0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1aed0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
1aee0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
1aef0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
1af00 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
1af10 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
1af20 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
1af30 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
1af40 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
1af50 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
1af60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
1af70 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
1af80 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
1af90 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
1afa0 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
1afb0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
1afc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1afd0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
1afe0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
1aff0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1b000 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1b010 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1b020 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1b030 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
1b040 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
1b050 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
1b060 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
1b070 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
1b080 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
1b090 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
1b0a0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b0b0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
1b0c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b0d0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1b0e0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
1b0f0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
1b100 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
1b110 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
1b120 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
1b130 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b140 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
1b150 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b160 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
1b170 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
1b180 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
1b190 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
1b1a0 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
1b1b0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
1b1c0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1b1d0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1b1e0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1b1f0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1b200 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76  ll returns..*/.v
1b210 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1b220 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1b230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b240 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1b250 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1b260 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1b270 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b280 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1b290 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1b2a0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1b2b0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1b2c0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1b2d0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1b2e0 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1b2f0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1b300 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1b310 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1b320 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1b330 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1b340 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1b350 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1b360 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1b370 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1b380 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1b390 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1b3a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1b3b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1b3c0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1b3d0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1b3e0 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1b3f0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1b400 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1b410 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1b420 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1b430 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1b440 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1b450 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1b460 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1b470 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1b480 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1b490 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1b4a0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1b4b0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1b4c0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1b4d0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1b4e0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1b4f0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1b500 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1b510 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1b520 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1b530 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1b540 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1b550 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1b560 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1b570 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1b580 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1b590 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1b5a0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1b5b0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1b5c0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1b5d0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1b5e0 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1b5f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1b600 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1b610 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1b620 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1b630 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1b640 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1b650 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1b660 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1b670 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1b680 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1b690 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1b6a0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1b6b0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1b6c0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1b6d0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1b6e0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1b6f0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1b700 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1b710 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1b720 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1b730 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1b740 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1b750 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1b760 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1b770 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1b780 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1b790 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1b7a0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1b7b0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1b7c0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1b7d0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b7e0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1b7f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1b800 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1b810 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1b820 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1b830 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1b840 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1b850 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1b860 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1b870 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
1b880 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1b890 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1b8a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1b8b0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1b8c0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1b8d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1b8e0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1b8f0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1b900 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1b910 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1b920 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1b930 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1b940 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1b950 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1b960 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1b970 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1b980 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1b990 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1b9a0 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1b9b0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1b9c0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1b9d0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1b9e0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1b9f0 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1ba00 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1ba10 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1ba20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1ba30 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1ba40 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1ba50 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1ba60 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1ba70 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1ba80 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1ba90 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1baa0 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1bab0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1bac0 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1bad0 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1bae0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1baf0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1bb00 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1bb10 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1bb20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1bb30 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1bb40 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1bb50 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1bb60 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1bb70 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1bb80 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1bb90 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1bba0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1bbb0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1bbc0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1bbd0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1bbe0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1bbf0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1bc00 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1bc10 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1bc20 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1bc30 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1bc40 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1bc50 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1bc60 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1bc70 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1bc80 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1bc90 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1bca0 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1bcb0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1bcc0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1bcd0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1bce0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1bcf0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1bd00 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1bd10 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1bd20 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1bd30 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1bd40 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1bd50 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1bd60 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1bd70 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1bd80 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1bd90 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1bda0 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1bdb0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1bdc0 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1bdd0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1bde0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1bdf0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1be00 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1be10 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1be20 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1be30 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1be40 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1be50 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1be60 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1be70 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1be80 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1be90 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1bea0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1beb0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1bec0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1bed0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1bee0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1bef0 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1bf00 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1bf10 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1bf20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1bf30 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1bf40 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1bf50 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1bf60 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1bf70 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1bf80 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1bf90 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1bfa0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1bfb0 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1bfc0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1bfd0 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1bfe0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1bff0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1c000 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1c010 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1c020 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1c030 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1c040 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1c050 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1c060 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1c070 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1c080 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1c090 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1c0a0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1c0b0 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1c0c0 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1c0d0 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1c0e0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1c0f0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1c100 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1c110 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1c120 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1c130 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1c140 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1c150 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1c160 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1c170 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1c180 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1c190 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1c1a0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1c1b0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1c1c0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1c1d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1c1e0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1c1f0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c200 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1c210 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1c220 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1c230 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1c240 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1c250 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1c260 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1c270 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1c280 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1c290 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1c2a0 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1c2b0 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1c2c0 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1c2d0 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1c2e0 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1c2f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1c300 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1c310 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1c320 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1c330 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1c340 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c350 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1c360 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1c370 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1c380 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1c390 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1c3a0 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1c3b0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1c3c0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1c3d0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1c3e0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1c3f0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1c400 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c410 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1c420 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c430 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1c440 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1c450 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1c460 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1c470 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1c480 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1c490 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c4a0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1c4b0 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1c4c0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1c4d0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1c4e0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1c4f0 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1c500 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1c510 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1c520 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1c530 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1c540 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1c550 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1c560 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1c570 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1c580 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1c590 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1c5a0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1c5b0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1c5c0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1c5d0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1c5e0 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1c5f0 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1c600 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1c610 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c620 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1c630 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1c640 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1c650 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1c660 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1c670 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1c680 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1c690 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1c6a0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1c6b0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1c6c0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1c6d0 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1c6e0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1c6f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1c700 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1c710 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1c720 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1c730 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1c740 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1c750 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1c760 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1c770 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1c780 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1c790 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1c7a0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1c7b0 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1c7c0 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1c7d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1c7e0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1c7f0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1c800 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1c810 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1c820 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1c830 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1c840 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1c850 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1c860 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1c870 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1c880 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1c890 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1c8a0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1c8b0 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1c8c0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1c8d0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1c8e0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1c8f0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1c900 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1c910 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1c920 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1c930 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1c940 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1c950 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1c960 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1c970 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1c980 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1c990 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1c9a0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1c9b0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1c9c0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1c9d0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1c9e0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1c9f0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1ca00 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1ca10 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1ca20 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1ca30 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1ca40 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1ca50 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1ca60 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1ca70 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1ca80 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1ca90 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1caa0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1cab0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1cac0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1cad0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1cae0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1caf0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1cb00 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1cb10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1cb20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1cb30 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1cb40 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1cb50 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1cb60 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1cb70 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1cb80 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1cb90 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1cba0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1cbb0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1cbc0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1cbd0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1cbe0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1cbf0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1cc00 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1cc10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1cc20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1cc30 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1cc40 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1cc50 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1cc60 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1cc70 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1cc80 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1cc90 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1cca0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1ccb0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1ccc0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1ccd0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1cce0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1ccf0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1cd00 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1cd10 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1cd20 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1cd30 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1cd40 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1cd50 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1cd60 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1cd70 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1cd80 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1cd90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cda0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1cdb0 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1cdc0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1cdd0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1cde0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1cdf0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1ce00 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1ce10 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1ce20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1ce30 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1ce40 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1ce50 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1ce60 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1ce70 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1ce80 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1ce90 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1cea0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1ceb0 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1cec0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1ced0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1cee0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cef0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1cf00 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1cf10 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1cf20 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1cf30 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1cf40 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1cf50 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1cf60 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cf70 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1cf80 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cf90 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1cfa0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1cfb0 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1cfc0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1cfd0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1cfe0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1cff0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1d000 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1d010 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1d020 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1d030 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d040 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1d050 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1d060 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1d070 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1d080 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1d090 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1d0a0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1d0b0 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1d0c0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1d0d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1d0e0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1d0f0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1d100 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1d110 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1d120 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1d130 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1d140 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1d150 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1d160 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1d170 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d180 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1d190 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1d1a0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1d1b0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1d1c0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1d1d0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1d1e0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1d1f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d200 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1d210 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1d220 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1d230 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1d240 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1d250 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1d260 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1d270 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1d280 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1d290 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1d2a0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1d2b0 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1d2c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1d2d0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1d2e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1d2f0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1d300 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1d310 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1d320 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1d330 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1d340 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1d350 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1d360 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1d370 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1d380 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1d390 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1d3a0 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1d3b0 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1d3c0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1d3d0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1d3e0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1d3f0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1d400 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1d410 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1d420 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1d430 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1d440 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1d450 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1d460 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1d470 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1d480 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1d490 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1d4a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1d4b0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1d4c0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1d4d0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1d4e0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1d4f0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1d500 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1d510 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1d520 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1d530 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1d540 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1d550 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1d560 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1d570 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1d580 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1d590 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1d5a0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1d5b0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1d5c0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1d5d0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1d5e0 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
1d5f0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d600 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1d610 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d620 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1d630 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1d640 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1d650 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1d660 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1d670 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1d680 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1d690 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1d6a0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1d6b0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1d6c0 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1d6d0 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1d6e0 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67  n K&R formatting
1d6f0 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75   options,.** plu
1d700 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1d710 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1d720 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64  ormats, detailed
1d730 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20   below..** Note 
1d740 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65  that some of the
1d750 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f   more obscure fo
1d760 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1d770 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20   from recent.** 
1d780 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61  C-library standa
1d790 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20  rds are omitted 
1d7a0 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d  from this implem
1d7b0 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  entation..**.** 
1d7c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1d7d0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1d7e0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1d7f0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1d800 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1d810 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1d820 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1d830 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1d840 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1d850 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1d860 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1d870 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1d880 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1d890 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1d8a0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1d8b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1d8c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d8d0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1d8e0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1d8f0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1d900 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1d910 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1d920 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1d930 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1d940 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1d950 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1d960 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1d970 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1d980 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1d990 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1d9a0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1d9b0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1d9c0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1d9d0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1d9e0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1d9f0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1da00 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1da10 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1da20 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1da30 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1da40 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1da50 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1da60 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1da70 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1da80 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1da90 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1daa0 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1dab0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1dac0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1dad0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1dae0 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1daf0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1db00 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1db10 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1db20 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1db30 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1db40 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1db50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1db60 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1db70 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1db80 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1db90 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1dba0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1dbb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1dbc0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1dbd0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1dbe0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1dbf0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1dc00 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1dc10 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1dc20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1dc30 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1dc40 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1dc50 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1dc60 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1dc70 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1dc80 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1dc90 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1dca0 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1dcb0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1dcc0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1dcd0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1dce0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1dcf0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1dd00 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1dd10 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1dd20 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1dd30 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1dd40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1dd50 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1dd60 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1dd70 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1dd80 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1dd90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1dda0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1ddb0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1ddc0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1ddd0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1dde0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1ddf0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1de00 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1de10 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1de20 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1de30 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1de40 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1de50 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1de60 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20  %q", "%Q", "%w" 
1de70 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1de80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1de90 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1dea0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1deb0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1dec0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1ded0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1dee0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1def0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1df00 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1df10 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1df20 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1df30 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1df40 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1df50 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1df60 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1df70 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1df80 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1df90 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1dfa0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1dfb0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1dfc0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1dfd0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1dfe0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1dff0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1e000 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1e010 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e020 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1e030 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1e040 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1e050 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1e060 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1e070 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1e080 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1e090 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1e0a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e0b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1e0c0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1e0d0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1e0e0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1e0f0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1e100 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1e110 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1e120 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1e130 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1e140 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e150 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1e160 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1e170 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1e180 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1e190 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1e1a0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1e1b0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1e1c0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1e1d0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1e1e0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1e1f0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1e200 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1e210 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1e220 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e230 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1e240 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1e250 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1e260 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1e270 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1e280 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1e290 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1e2a0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1e2b0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1e2c0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1e2d0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1e2e0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1e2f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e300 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1e310 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1e320 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1e330 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1e340 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1e350 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1e360 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1e370 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1e380 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1e390 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1e3a0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1e3b0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1e3c0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1e3d0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1e3e0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1e3f0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1e400 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1e410 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1e420 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1e430 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1e440 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1e450 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1e460 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1e470 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1e480 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1e490 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1e4a0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1e4b0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1e4c0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1e4d0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1e4e0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1e4f0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1e500 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1e510 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1e520 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1e530 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1e540 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1e550 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1e560 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1e570 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1e580 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1e590 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1e5a0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1e5b0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1e5c0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1e5d0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1e5e0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1e5f0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1e600 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b  ng option is lik
1e610 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68  e "%q" except th
1e620 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f  at it expects to
1e630 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  .** be contained
1e640 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71   within double-q
1e650 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66  uotes instead of
1e660 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20   single quotes, 
1e670 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65  and it.** escape
1e680 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f  s the double-quo
1e690 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73  te character ins
1e6a0 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67  tead of the sing
1e6b0 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72  le-quote.** char
1e6c0 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25  acter.)^  The "%
1e6d0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1e6e0 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64  tion is intended
1e6f0 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65   for safely inse
1e700 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61  rting.** table a
1e710 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  nd column names 
1e720 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74  into a construct
1e730 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1e740 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1e750 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1e760 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1e770 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1e780 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1e790 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1e7a0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1e7b0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1e7c0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1e7d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e7e0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1e7f0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1e800 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1e810 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1e820 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1e830 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1e840 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1e850 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1e860 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1e870 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1e880 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1e890 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1e8a0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1e8b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1e8c0 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1e8d0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1e8e0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1e8f0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1e900 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1e910 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1e920 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1e930 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1e940 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1e950 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1e960 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1e970 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1e980 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1e990 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1e9a0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1e9b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1e9c0 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1e9d0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1e9e0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1e9f0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1ea00 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1ea10 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1ea20 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1ea30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ea40 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1ea50 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1ea60 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1ea70 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1ea80 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1ea90 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1eaa0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1eab0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1eac0 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1ead0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1eae0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1eaf0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1eb00 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1eb10 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1eb20 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1eb30 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1eb40 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1eb50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1eb60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1eb70 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
1eb80 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
1eb90 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
1eba0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
1ebb0 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
1ebc0 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
1ebd0 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1ebe0 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
1ebf0 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
1ec00 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1ec10 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1ec20 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1ec30 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1ec40 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1ec50 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1ec60 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1ec70 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1ec80 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1ec90 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1eca0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1ecb0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1ecc0 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1ecd0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1ece0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1ecf0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1ed00 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1ed10 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1ed20 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1ed30 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1ed40 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1ed50 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1ed60 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1ed70 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1ed80 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1ed90 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1eda0 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1edb0 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1edc0 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1edd0 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1ede0 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1edf0 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1ee00 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1ee10 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1ee20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1ee30 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1ee40 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1ee50 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1ee60 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1ee70 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1ee80 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1ee90 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1eea0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1eeb0 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
1eec0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1eed0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1eee0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1eef0 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
1ef00 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
1ef10 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
1ef20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1ef30 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
1ef40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1ef50 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1ef60 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1ef70 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1ef80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
1ef90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
1efa0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1efb0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1efc0 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1efd0 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1efe0 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1eff0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1f000 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1f010 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
1f020 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f030 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
1f040 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1f050 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1f060 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1f070 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1f080 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
1f090 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
1f0a0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1f0b0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1f0c0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1f0d0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1f0e0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** 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 20 61 72 65 20 63 6f 70 69 65  cation are copie
1f110 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1f120 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1f130 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1f140 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1f150 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
1f160 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1f170 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1f180 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f190 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
1f1a0 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
1f1b0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
1f1c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1f1d0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1f1e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f1f0 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
1f200 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
1f210 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
1f220 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f230 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
1f240 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
1f250 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
1f260 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
1f270 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
1f280 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
1f290 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
1f2a0 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
1f2b0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
1f2c0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1f2d0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1f2e0 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
1f2f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
1f300 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f310 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
1f320 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1f330 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
1f340 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
1f350 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
1f360 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
1f370 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1f380 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
1f390 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
1f3a0 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
1f3b0 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
1f3c0 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
1f3d0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
1f3e0 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
1f3f0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
1f400 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1f410 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
1f420 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
1f430 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
1f440 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
1f450 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
1f460 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
1f470 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
1f480 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
1f490 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f4a0 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
1f4b0 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
1f4c0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
1f4d0 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
1f4e0 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
1f4f0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
1f500 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
1f510 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
1f520 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1f530 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
1f540 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1f550 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1f560 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1f570 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
1f580 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1f590 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1f5a0 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1f5b0 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1f5c0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1f5d0 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1f5e0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1f5f0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1f600 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1f610 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1f620 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1f630 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1f640 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1f650 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1f660 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1f670 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1f680 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1f690 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1f6a0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1f6b0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1f6c0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1f6d0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1f6e0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1f6f0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1f700 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1f710 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1f720 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1f730 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1f740 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1f750 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1f760 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1f770 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1f780 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1f790 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1f7a0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1f7b0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1f7c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1f7d0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1f7e0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1f7f0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1f800 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1f810 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1f820 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1f830 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1f840 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1f850 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1f860 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1f870 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1f880 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1f890 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1f8a0 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1f8b0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1f8c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1f8d0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1f8e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f8f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1f900 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1f910 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1f920 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1f930 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1f940 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1f950 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1f960 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1f970 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f980 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1f990 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1f9a0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1f9b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1f9c0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1f9d0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1f9e0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1f9f0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1fa00 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1fa10 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1fa20 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1fa30 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1fa40 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1fa50 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1fa60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1fa70 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
1fa80 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
1fa90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1faa0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
1fab0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1fac0 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
1fad0 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1fae0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1faf0 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
1fb00 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
1fb10 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1fb20 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1fb30 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1fb40 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1fb50 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1fb60 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1fb70 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1fb80 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1fb90 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1fba0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1fbb0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1fbc0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1fbd0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1fbe0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1fbf0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1fc00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1fc10 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1fc20 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1fc30 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1fc40 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1fc50 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1fc60 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1fc70 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1fc80 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1fc90 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1fca0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1fcb0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1fcc0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1fcd0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1fce0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1fcf0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1fd00 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1fd10 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1fd20 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1fd30 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1fd40 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1fd50 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1fd60 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1fd70 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1fd80 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1fd90 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1fda0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1fdb0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1fdc0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1fdd0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1fde0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1fdf0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1fe00 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1fe10 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1fe20 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1fe30 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1fe40 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1fe50 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1fe60 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1fe70 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1fe80 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1fe90 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1fea0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1feb0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1fec0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1fed0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1fee0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1fef0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1ff00 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1ff10 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1ff20 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1ff30 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1ff40 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1ff50 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
1ff60 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1ff70 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
1ff80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1ff90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1ffa0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1ffb0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1ffc0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1ffd0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1ffe0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1fff0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
20000 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
20010 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
20020 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
20030 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
20040 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
20050 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
20060 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
20070 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
20080 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
20090 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
200a0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
200b0 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
200c0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
200d0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
200e0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
200f0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
20100 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
20110 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
20120 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
20130 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
20140 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
20150 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
20160 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
20170 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
20180 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
20190 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
201a0 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
201b0 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
201c0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
201d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
201e0 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
201f0 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
20200 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
20210 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
20220 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
20230 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
20240 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
20250 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
20260 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
20270 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
20280 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
20290 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
202a0 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
202b0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
202c0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
202d0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
202e0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
202f0 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
20300 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
20310 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
20320 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
20330 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
20340 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
20350 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
20360 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
20370 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
20380 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
20390 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
203a0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
203b0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
203c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
203d0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
203e0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
203f0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
20400 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f  sqlite3.** KEYWO
20410 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72  RDS: {authorizer
20420 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a   callback}.**.**
20430 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
20440 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
20450 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20460 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
20470 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
20480 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
20490 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
204a0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
204b0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
204c0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
204d0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
204e0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
204f0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
20500 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20510 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
20520 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
20530 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
20540 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
20550 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
20560 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c  epare16()], [sql
20570 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20580 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71  2()],.** and [sq
20590 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
205a0 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v3()].  ^At vari
205b0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
205c0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
205d0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
205e0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
205f0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
20600 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
20610 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
20620 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20630 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
20640 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
20650 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
20660 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
20670 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
20680 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
20690 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
206a0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
206b0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
206c0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
206d0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
206e0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
206f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
20700 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
20710 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
20720 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
20730 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
20740 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
20750 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
20760 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
20770 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
20780 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
20790 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
207a0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
207b0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
207c0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
207d0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
207e0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
207f0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f  _prepare_v3()] o
20800 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
20810 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
20820 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
20830 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
20840 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
20850 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
20860 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20870 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
20880 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
20890 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
208a0 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
208b0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
208c0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
208d0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
208e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
208f0 5f 76 33 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v3()] or equiva
20900 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
20910 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
20920 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
20930 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
20940 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
20950 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
20960 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
20970 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
20980 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
20990 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
209a0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
209b0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
209c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
209d0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
209e0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
209f0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
20a00 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
20a10 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
20a20 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
20a30 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
20a40 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
20a50 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
20a60 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
20a70 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
20a80 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
20a90 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
20aa0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
20ab0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69   callback are ei
20ac0 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ther NULL pointe
20ad0 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69  rs or zero-termi
20ae0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  nated strings.**
20af0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
20b00 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
20b10 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
20b20 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
20b30 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ed..** Applicati
20b40 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ons must always 
20b50 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65  be prepared to e
20b60 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20  ncounter a NULL 
20b70 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a  pointer in any.*
20b80 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74  * of the third t
20b90 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68  hrough the sixth
20ba0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
20bb0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
20bc0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
20bd0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
20be0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
20bf0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
20c00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20c10 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
20c20 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
20c30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20c40 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
20c50 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
20c60 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
20c70 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
20c80 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
20c90 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
20ca0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
20cb0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
20cc0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
20cd0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
20ce0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
20cf0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
20d00 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
20d10 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
20d20 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
20d30 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
20d40 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20  table..** ^When 
20d50 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72  a table is refer
20d60 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45  enced by a [SELE
20d70 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  CT] but no colum
20d80 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20  n values are.** 
20d90 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74  extracted from t
20da0 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65  hat table (for e
20db0 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72  xample in a quer
20dc0 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43  y like.** "SELEC
20dd0 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20  T count(*) FROM 
20de0 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b  tab") then the [
20df0 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74  SQLITE_READ] aut
20e00 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20e10 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  .** is invoked o
20e20 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62  nce for that tab
20e30 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e  le with a column
20e40 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e   name that is an
20e50 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
20e60 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
20e70 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
20e80 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
20e90 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20ea0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
20eb0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
20ec0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
20ed0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
20ee0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
20ef0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
20f00 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
20f10 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
20f20 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
20f30 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
20f40 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
20f50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20f60 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
20f70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
20f80 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
20f90 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
20fa0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
20fb0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
20fc0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
20fd0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
20fe0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
20ff0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
21000 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
21010 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
21020 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
21030 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
21040 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
21050 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
21060 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
21070 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
21080 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
21090 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
210a0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
210b0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
210c0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
210d0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
210e0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
210f0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
21100 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
21110 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
21120 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
21130 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
21140 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
21150 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
21160 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
21170 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
21180 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
21190 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
211a0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
211b0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
211c0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
211d0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
211e0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
211f0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
21200 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
21210 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
21220 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
21230 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
21240 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
21250 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
21260 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
21270 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
21280 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
21290 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
212a0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
212b0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
212c0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
212d0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
212e0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
212f0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
21300 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
21310 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
21320 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
21330 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
21340 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
21350 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
21360 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
21370 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
21380 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
21390 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
213a0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
213b0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
213c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
213d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
213e0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
213f0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
21400 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
21410 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21420 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
21430 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21440 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
21450 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
21460 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 20 5b 73  are_v3()] and [s
21470 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
21480 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
21490 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
214a0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
214b0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
214c0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
214d0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
214e0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
214f0 70 61 72 65 5f 76 33 28 29 5d 20 69 73 20 75 73  pare_v3()] is us
21500 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
21510 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
21520 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
21530 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
21540 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
21550 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
21560 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
21570 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
21580 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
21590 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
215a0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
215b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
215c0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
215d0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
215e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
215f0 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
21600 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
21610 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
21620 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
21630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21640 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
21650 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
21660 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
21670 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
21680 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
21690 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
216a0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
216b0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
216c0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
216d0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
216e0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
216f0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
21700 65 70 61 72 65 5f 76 33 28 29 20 74 6f 20 72 65  epare_v3() to re
21710 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
21720 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
21730 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
21740 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
21750 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
21760 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
21770 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
21780 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
21790 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
217a0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
217b0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
217c0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
217d0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
217e0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
217f0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
21800 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21810 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
21820 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
21830 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
21840 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
21850 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
21860 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
21870 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
21880 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
21890 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
218a0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
218b0 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
218c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
218d0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
218e0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
218f0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
21900 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
21910 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
21920 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
21930 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
21940 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
21950 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
21960 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
21970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
21980 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
21990 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
219a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
219b0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
219c0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
219d0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
219e0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
219f0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
21a00 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
21a10 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
21a20 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
21a30 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
21a40 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
21a50 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
21a60 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
21a70 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21a80 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
21a90 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
21aa0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
21ab0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
21ac0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
21ad0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
21ae0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
21af0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
21b00 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
21b10 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
21b20 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
21b30 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
21b40 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
21b50 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
21b60 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
21b70 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
21b80 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
21b90 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
21ba0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
21bb0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
21bc0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
21bd0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
21be0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
21bf0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
21c00 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
21c10 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
21c20 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
21c30 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
21c40 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
21c50 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
21c60 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
21c70 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
21c80 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
21c90 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
21ca0 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
21cb0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
21cc0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
21cd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21ce0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21cf0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
21d00 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
21d10 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
21d20 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
21d30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
21d40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21d50 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
21d60 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
21d70 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
21d80 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
21d90 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
21da0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
21db0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
21dc0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
21dd0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
21de0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
21df0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
21e00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e20 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
21e30 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
21e40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
21e50 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21e60 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21e70 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
21e80 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21e90 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21ea0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21eb0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
21ec0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21ed0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21ee0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21ef0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21f00 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
21f10 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
21f20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
21f30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21f40 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21f50 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
21f60 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21f70 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21f80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21f90 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21fa0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
21fb0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
21fc0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21fd0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21fe0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21ff0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
22000 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22010 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22020 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22030 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
22040 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
22050 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22060 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22070 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22080 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
22090 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
220a0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
220b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
220c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
220d0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
220e0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
220f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22100 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22110 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22120 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
22130 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
22140 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22150 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22160 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22170 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
22180 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
22190 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
221a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
221b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
221c0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
221d0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
221e0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
221f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22210 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
22220 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
22230 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22240 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22250 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22260 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
22270 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
22280 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
22290 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
222a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
222b0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
222c0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
222d0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
222e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
222f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22300 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
22310 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
22320 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22330 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22340 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
22350 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
22360 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
22370 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22380 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22390 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
223a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
223b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
223c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
223d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
223e0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
223f0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
22400 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
22410 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
22420 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
22430 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
22440 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
22450 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22460 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
22470 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22480 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
22490 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
224a0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
224b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
224c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
224d0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
224e0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
224f0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
22500 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22510 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22520 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
22530 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
22540 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22550 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
22560 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22570 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
22580 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
22590 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
225a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
225b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
225c0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
225d0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
225e0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
225f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22600 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22610 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
22620 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
22630 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
22640 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22650 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22660 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
22670 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
22680 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
22690 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
226a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
226b0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
226c0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
226d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
226e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
226f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22700 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
22710 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
22720 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
22730 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
22740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22750 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
22760 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
22770 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
22780 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
22790 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
227a0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
227b0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
227c0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
227d0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
227e0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
227f0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
22800 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
22810 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
22820 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
22830 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
22840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22850 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
22860 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
22870 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
22880 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
22890 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
228a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
228b0 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
228c0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
228d0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
228e0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
228f0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
22900 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22910 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
22920 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
22930 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
22940 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
22950 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
22960 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
22970 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
22980 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
22990 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
229a0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
229b0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
229c0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
229d0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
229e0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
229f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
22a00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
22a10 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
22a20 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
22a30 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
22a40 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
22a50 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
22a60 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
22a70 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
22a80 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
22a90 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
22aa0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22ab0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
22ac0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
22ad0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
22ae0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
22af0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
22b00 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
22b10 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
22b20 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
22b30 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
22b40 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
22b50 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
22b60 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
22b70 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
22b80 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
22b90 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
22ba0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
22bb0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
22bc0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
22bd0 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
22be0 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
22bf0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
22c00 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
22c10 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
22c20 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
22c30 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
22c40 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
22c50 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
22c60 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
22c70 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22c80 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
22c90 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
22ca0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
22cb0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
22cc0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
22cd0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
22ce0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
22cf0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
22d00 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
22d10 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
22d20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
22d30 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
22d40 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
22d50 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
22d60 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
22d70 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
22d80 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
22d90 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
22da0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
22db0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
22dc0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
22dd0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
22de0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
22df0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
22e00 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
22e10 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
22e20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
22e30 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22e40 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
22e50 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
22e60 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
22e70 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
22e80 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
22e90 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
22ea0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
22eb0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
22ec0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
22ed0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
22ee0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
22ef0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
22f00 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
22f10 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
22f20 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
22f30 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
22f40 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
22f50 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
22f60 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
22f70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
22f80 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
22f90 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
22fa0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
22fb0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
22fc0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
22fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
22fe0 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
22ff0 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
23000 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
23010 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
23020 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
23030 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
23040 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
23050 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
23060 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
23070 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
23080 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72  logic.  The thir
23090 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
230a0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
230b0 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  v2()] is an OR-e
230c0 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
230d0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
230e0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
230f0 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
23100 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
23110 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
23120 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
23130 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
23140 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
23150 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
23160 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
23170 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
23180 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
23190 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
231a0 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
231b0 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
231c0 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
231d0 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
231e0 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
231f0 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
23200 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
23210 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
23220 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
23230 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
23240 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
23250 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
23260 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
23270 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
23280 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
23290 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
232a0 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
232b0 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
232c0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
232d0 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
232e0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
232f0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
23300 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
23310 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
23320 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
23330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23340 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
23350 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
23360 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
23370 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
23380 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
23390 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
233a0 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
233b0 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
233c0 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
233d0 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
233e0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
233f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23400 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
23410 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
23420 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
23430 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
23440 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
23450 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
23460 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
23470 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23480 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
23490 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
234a0 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
234b0 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
234c0 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
234d0 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
234e0 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
234f0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
23500 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
23510 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
23520 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
23530 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
23540 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
23550 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
23560 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
23570 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
23580 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
23590 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
235a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
235b0 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
235c0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
235d0 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
235e0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
235f0 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
23600 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
23610 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
23620 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
23630 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
23640 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
23650 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
23660 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
23670 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
23680 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
23690 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
236a0 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
236b0 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
236c0 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
236d0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
236e0 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
236f0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
23700 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
23710 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
23720 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
23730 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
23740 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23750 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
23760 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
23770 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
23780 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
23790 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
237a0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
237b0 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
237c0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
237d0 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
237e0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
237f0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
23800 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
23810 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
23820 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
23830 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
23840 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23850 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23860 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
23870 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
23880 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
23890 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
238a0 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
238b0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
238c0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
238d0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
238e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
238f0 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ked when a datab
23900 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
23910 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
23920 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
23930 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23940 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23950 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
23960 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
23970 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
23980 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
23990 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
239a0 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
239b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
239c0 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
239d0 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
239e0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
239f0 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
23a00 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
23a10 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
23a20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23a30 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
23a40 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
23a50 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
23a60 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
23a70 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
23a80 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
23a90 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
23aa0 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
23ab0 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
23ac0 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
23ad0 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
23ae0 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
23af0 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
23b00 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
23b10 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
23b20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
23b30 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
23b40 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
23b50 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
23b60 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
23b70 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
23b80 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
23b90 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
23ba0 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
23bb0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
23bc0 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
23bd0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23be0 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
23bf0 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
23c00 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
23c10 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
23c20 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
23c30 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
23c40 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
23c50 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
23c60 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
23c70 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
23c80 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
23c90 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
23ca0 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
23cb0 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
23cc0 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
23cd0 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
23ce0 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
23cf0 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
23d00 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
23d10 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
23d20 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
23d30 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
23d40 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
23d50 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
23d60 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
23d70 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
23d80 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
23d90 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
23da0 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
23db0 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
23dc0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
23dd0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
23de0 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
23df0 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
23e00 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
23e10 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
23e20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
23e30 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
23e40 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
23e50 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
23e60 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
23e70 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
23e80 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
23e90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23ea0 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
23eb0 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
23ec0 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
23ed0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
23ee0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
23ef0 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
23f00 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
23f10 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
23f20 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
23f30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23f40 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
23f50 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
23f60 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a  d uMask,.  int(*
23f70 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
23f80 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
23f90 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
23fa0 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
23fb0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
23fc0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
23fd0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
23fe0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
23ff0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
24000 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
24010 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
24020 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
24030 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
24040 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
24050 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
24060 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
24070 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
24080 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
24090 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
240a0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
240b0 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
240c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
240d0 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
240e0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
240f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
24100 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
24110 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
24120 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
24130 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
24140 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
24150 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
24160 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
24170 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
24180 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
24190 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
241a0 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
241b0 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
241c0 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
241d0 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
241e0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
241f0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
24200 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
24210 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
24220 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
24230 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
24240 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
24250 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
24260 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
24270 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
24280 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
24290 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
242a0 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
242b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
242c0 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
242d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
242e0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
242f0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
24300 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
24310 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
24320 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
24330 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
24340 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
24350 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
24360 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
24370 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
24380 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
24390 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
243a0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
243b0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
243c0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
243d0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
243e0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
243f0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
24400 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
24410 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
24420 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
24430 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
24440 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24450 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
24460 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
24470 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
24480 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
24490 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
244a0 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
244b0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
244c0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
244d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
244e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
244f0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
24500 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
24510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
24520 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
24530 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
24540 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
24550 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
24560 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
24570 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
24580 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
24590 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
245a0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
245b0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
245c0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
245d0 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
245e0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
245f0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
24600 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
24610 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
24620 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
24630 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24640 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
24650 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
24660 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
24670 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
24680 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
24690 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
246a0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
246b0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
246c0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
246d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
246e0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
246f0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
24700 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
24710 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
24720 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
24730 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
24740 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
24750 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
24760 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
24770 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
24780 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
24790 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
247a0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
247b0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
247c0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
247d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
247e0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
247f0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
24800 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24810 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
24820 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
24830 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
24840 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
24850 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
24860 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
24870 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
24880 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
24890 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
248a0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
248b0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
248c0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
248d0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
248e0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
248f0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
24900 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
24910 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
24920 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
24930 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
24940 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
24950 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
24960 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
24970 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
24980 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24990 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
249a0 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
249b0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
249c0 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
249d0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
249e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
249f0 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
24a00 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
24a10 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
24a20 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
24a30 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
24a40 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
24a50 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
24a60 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
24a70 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
24a80 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
24a90 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
24aa0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
24ab0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
24ac0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
24ad0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
24ae0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
24af0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24b00 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
24b10 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
24b20 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
24b30 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
24b40 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
24b50 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
24b60 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
24b70 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
24b80 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
24b90 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
24ba0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
24bb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24bc0 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
24bd0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
24be0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
24bf0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
24c00 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
24c10 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
24c20 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
24c30 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
24c40 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
24c50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
24c60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
24c70 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
24c80 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
24c90 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
24ca0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
24cb0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
24cc0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
24cd0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
24ce0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
24cf0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
24d00 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
24d10 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
24d20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
24d30 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
24d40 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
24d50 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
24d60 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
24d70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24d80 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24d90 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
24da0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
24db0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
24dc0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
24dd0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
24de0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
24df0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
24e00 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
24e10 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
24e20 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
24e30 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
24e40 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
24e50 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
24e60 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
24e70 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
24e80 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
24e90 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
24ea0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
24eb0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
24ec0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
24ed0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
24ee0 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
24ef0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
24f00 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
24f10 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
24f20 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
24f30 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
24f40 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
24f50 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
24f60 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
24f70 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
24f80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
24f90 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
24fa0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
24fb0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
24fc0 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
24fd0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
24fe0 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
24ff0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
25000 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
25010 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
25020 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
25030 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
25040 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
25050 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
25060 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
25070 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25080 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
25090 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
250a0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
250b0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
250c0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
250d0 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
250e0 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
250f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
25100 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
25110 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
25120 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
25130 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
25140 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25150 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
25160 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
25170 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
25180 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
25190 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
251a0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
251b0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
251c0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
251d0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
251e0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
251f0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
25200 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
25210 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
25220 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
25230 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
25240 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
25250 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
25260 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
25270 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
25280 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
25290 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
252a0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
252b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
252c0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
252d0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
252e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
252f0 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
25300 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
25310 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
25320 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
25330 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
25340 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
25350 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25360 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
25370 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
25380 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
25390 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
253a0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
253b0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
253c0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
253d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
253e0 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
253f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
25400 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
25410 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
25420 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
25430 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
25440 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
25450 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
25460 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
25470 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
25480 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
25490 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
254a0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
254b0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
254c0 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
254d0 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
254e0 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
254f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25500 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
25510 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
25520 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
25530 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
25540 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
25550 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
25560 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
25570 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
25580 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
25590 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
255a0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
255b0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
255c0 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
255d0 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
255e0 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
255f0 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
25600 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
25610 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
25620 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
25630 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
25640 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
25650 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
25660 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
25670 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
25680 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
25690 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
256a0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
256b0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
256c0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
256d0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
256e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
256f0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
25700 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
25710 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
25720 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
25730 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
25740 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
25750 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
25760 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
25770 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
25780 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
25790 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
257a0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
257b0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
257c0 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
257d0 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
257e0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
257f0 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
25800 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
25810 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
25820 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
25830 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
25840 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25850 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
25860 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
25870 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
25880 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
25890 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
258a0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
258b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
258c0 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
258d0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
258e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
258f0 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
25900 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
25910 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
25920 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
25930 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
25940 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
25950 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
25960 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
25970 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
25980 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
25990 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
259a0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
259b0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
259c0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
259d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
259e0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
259f0 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
25a00 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
25a10 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
25a20 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
25a30 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
25a40 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
25a50 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
25a60 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
25a70 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
25a80 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
25a90 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
25aa0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
25ab0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
25ac0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
25ad0 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
25ae0 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
25af0 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
25b00 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
25b10 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
25b20 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
25b30 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
25b40 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
25b50 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
25b60 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
25b70 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
25b80 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
25b90 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
25ba0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
25bb0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
25bc0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
25bd0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
25be0 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
25bf0 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
25c00 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
25c10 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
25c20 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
25c30 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
25c40 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
25c50 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
25c60 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
25c70 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
25c80 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
25c90 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
25ca0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
25cb0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
25cc0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
25cd0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
25ce0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
25cf0 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
25d00 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
25d10 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
25d20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
25d30 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
25d40 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
25d50 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
25d60 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
25d70 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
25d80 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
25d90 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
25da0 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
25db0 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
25dc0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
25dd0 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
25de0 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
25df0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
25e00 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
25e10 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
25e20 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
25e30 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
25e40 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
25e50 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
25e60 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
25e70 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
25e80 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
25e90 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
25ea0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
25eb0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
25ec0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
25ed0 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
25ee0 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
25ef0 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
25f00 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
25f10 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
25f20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
25f30 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
25f40 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
25f50 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
25f60 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
25f70 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
25f80 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
25f90 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
25fa0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
25fb0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
25fc0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
25fd0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
25fe0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
25ff0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
26000 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
26010 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
26020 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
26030 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
26040 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
26050 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
26060 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
26070 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
26080 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
26090 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
260a0 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
260b0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
260c0 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
260d0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
260e0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
260f0 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
26100 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
26110 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
26120 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
26130 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
26140 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
26150 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
26160 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
26170 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
26180 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
26190 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
261a0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
261b0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
261c0 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
261d0 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
261e0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
261f0 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
26200 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
26210 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
26220 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
26230 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
26240 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
26250 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
26260 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
26270 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
26280 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
26290 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
262a0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
262b0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
262c0 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
262d0 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
262e0 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
262f0 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
26300 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
26310 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
26320 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
26330 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
26340 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
26350 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
26360 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
26370 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
26380 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
26390 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
263a0 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
263b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
263c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
263d0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
263e0 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
263f0 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
26400 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
26410 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
26420 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
26430 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
26440 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
26450 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
26460 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
26470 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
26480 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
26490 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
264a0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
264b0 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
264c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
264d0 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
264e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
264f0 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
26500 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
26510 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
26520 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
26530 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
26540 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
26550 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
26560 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
26570 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
26580 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
26590 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
265a0 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
265b0 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
265c0 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
265d0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
265e0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
265f0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
26600 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
26610 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
26620 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
26630 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
26640 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
26650 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
26660 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
26670 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
26680 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
26690 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
266a0 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
266b0 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
266c0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
266d0 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
266e0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
266f0 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
26700 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
26710 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
26720 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
26730 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
26740 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
26750 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
26760 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
26770 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
26780 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
26790 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
267a0 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
267b0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
267c0 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
267d0 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
267e0 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
267f0 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
26800 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
26810 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
26820 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
26830 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
26840 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
26850 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
26860 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
26870 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
26880 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
26890 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
268a0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
268b0 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
268c0 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
268d0 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
268e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
268f0 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
26900 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
26910 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
26920 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
26930 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
26940 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
26950 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
26960 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
26970 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
26980 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
26990 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
269a0 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
269b0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
269c0 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
269d0 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
269e0 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
269f0 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
26a00 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
26a10 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
26a20 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
26a30 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
26a40 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
26a50 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
26a60 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
26a70 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
26a80 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
26a90 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
26aa0 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
26ab0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
26ac0 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
26ad0 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
26ae0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
26af0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
26b00 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
26b10 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
26b20 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
26b30 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
26b40 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
26b50 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
26b60 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
26b70 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
26b80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
26b90 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
26ba0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
26bb0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
26bc0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
26bd0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
26be0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
26bf0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
26c00 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
26c10 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
26c20 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
26c30 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
26c40 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
26c50 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
26c60 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
26c70 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
26c80 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
26c90 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
26ca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
26cb0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
26cc0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
26cd0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
26ce0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26cf0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26d00 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
26d10 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
26d20 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
26d30 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
26d40 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
26d50 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26d60 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
26d70 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
26d80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
26d90 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
26da0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
26db0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
26dc0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
26dd0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
26de0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
26df0 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
26e00 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
26e10 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
26e20 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
26e30 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
26e40 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
26e50 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
26e60 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
26e70 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
26e80 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
26e90 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
26ea0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
26eb0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
26ec0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
26ed0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
26ee0 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
26ef0 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
26f00 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
26f10 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
26f20 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
26f30 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
26f40 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
26f50 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
26f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
26f70 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
26f80 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26f90 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
26fa0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
26fb0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26fc0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
26fd0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
26fe0 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
26ff0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
27000 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
27010 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
27020 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
27030 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
27040 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
27050 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
27060 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
27070 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
27080 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
27090 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
270a0 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
270b0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
270c0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
270d0 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
270e0 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
270f0 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
27100 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
27110 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
27120 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
27130 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
27140 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
27150 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
27160 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
27170 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
27180 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
27190 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
271a0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
271b0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
271c0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
271d0 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
271e0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
271f0 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
27200 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
27210 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
27220 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
27230 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
27240 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
27250 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
27260 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
27270 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
27280 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
27290 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
272a0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
272b0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
272c0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
272d0 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
272e0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
272f0 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
27300 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
27310 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
27320 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
27330 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
27340 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
27350 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
27360 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
27370 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
27380 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
27390 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
273a0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
273b0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
273c0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
273d0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
273e0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
273f0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
27400 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
27410 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
27420 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
27430 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
27440 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
27450 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
27460 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
27470 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
27480 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
27490 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
274a0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
274b0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
274c0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
274d0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
274e0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
274f0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
27500 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
27510 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
27520 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
27530 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
27540 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
27550 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
27560 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
27570 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
27580 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
27590 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
275a0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
275b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
275c0 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
275d0 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
275e0 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
275f0 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
27600 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
27610 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
27620 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
27630 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
27640 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
27650 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
27660 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
27670 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
27680 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
27690 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
276a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
276b0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
276c0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
276d0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
276e0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
276f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
27700 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
27710 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
27720 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
27730 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27740 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
27750 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27760 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
27770 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
27780 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
27790 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
277a0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
277b0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
277c0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
277d0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
277e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
277f0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
27800 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
27810 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
27820 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
27830 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
27840 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
27850 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
27860 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
27870 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
27880 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
27890 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
278a0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
278b0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
278c0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
278d0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
278e0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
278f0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
27900 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
27910 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
27920 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
27930 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
27940 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
27950 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
27960 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
27970 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
27980 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
27990 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
279a0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
279b0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
279c0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
279d0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
279e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
279f0 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
27a00 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
27a10 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
27a20 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
27a30 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
27a40 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
27a50 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27a60 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
27a70 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
27a80 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
27a90 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
27aa0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
27ab0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
27ac0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
27ad0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
27ae0 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
27af0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
27b00 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
27b10 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
27b20 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
27b30 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
27b40 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
27b50 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
27b60 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
27b70 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27b80 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
27b90 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
27ba0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
27bb0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
27bc0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
27bd0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
27be0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
27bf0 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
27c00 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
27c10 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27c20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
27c30 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
27c40 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
27c50 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
27c60 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
27c70 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
27c80 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
27c90 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
27ca0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
27cb0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
27cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27cd0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27ce0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
27cf0 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
27d00 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
27d10 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
27d20 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
27d30 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
27d40 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
27d50 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
27d60 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
27d70 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
27d80 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
27d90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
27da0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
27db0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
27dc0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
27dd0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
27de0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
27df0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27e00 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
27e10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27e20 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
27e30 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
27e40 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
27e50 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
27e60 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
27e70 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
27e80 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
27e90 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
27ea0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
27eb0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
27ec0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
27ed0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
27ee0 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
27ef0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
27f00 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
27f10 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
27f20 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
27f30 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
27f40 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
27f50 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
27f60 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
27f70 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
27f80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
27f90 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
27fa0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
27fb0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
27fc0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
27fd0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
27fe0 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
27ff0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
28000 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
28010 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
28020 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
28030 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
28040 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28050 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
28060 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
28070 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
28080 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
28090 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
280a0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
280b0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
280c0 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
280d0 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
280e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
280f0 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
28100 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
28110 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
28120 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
28130 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
28140 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
28150 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28160 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  3.**.** ^If the 
28170 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69  most recent sqli
28180 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
28190 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a  ssociated with .
281a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
281b0 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65  nection] D faile
281c0 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  d, then the sqli
281d0 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69  te3_errcode(D) i
281e0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
281f0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
28200 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
28210 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
28220 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74  t code] for that
28230 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a  .** API call..**
28240 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
28250 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73  ent API call was
28260 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20   successful,.** 
28270 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
28280 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
28290 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
282a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54  undefined..** ^T
282b0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
282c0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
282d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
282e0 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
282f0 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
28300 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
28310 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
28320 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
28330 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
28340 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
28350 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
28360 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
28370 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
28380 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
28390 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
283a0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
283b0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
283c0 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
283d0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
283e0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
283f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
28400 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
28410 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
28420 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
28430 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
28440 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
28450 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
28460 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
28470 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
28480 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
28490 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
284a0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
284b0 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
284c0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
284d0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
284e0 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
284f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28500 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
28510 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
28520 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
28530 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
28540 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
28550 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
28560 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
28570 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
28580 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
28590 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
285a0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
285b0 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
285c0 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
285d0 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
285e0 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
285f0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
28600 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
28610 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
28620 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
28630 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
28640 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
28650 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
28660 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
28670 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
28680 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
28690 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
286a0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
286b0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
286c0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
286d0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
286e0 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
286f0 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
28700 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
28710 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
28720 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
28730 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
28740 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
28750 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
28760 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
28770 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
28780 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
28790 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
287a0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
287b0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
287c0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
287d0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
287e0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
287f0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
28800 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
28810 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
28820 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
28830 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
28840 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
28850 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
28860 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
28870 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
28880 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
28890 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
288a0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
288b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
288c0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
288d0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
288e0 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
288f0 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
28900 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28910 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
28920 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
28930 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
28940 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
28950 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
28960 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
28970 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
28980 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
28990 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
289a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
289b0 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
289c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
289d0 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
289e0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
289f0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
28a00 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
28a10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28a20 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
28a30 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
28a40 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
28a50 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
28a60 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
28a70 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
28a80 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
28a90 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
28aa0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
28ab0 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
28ac0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
28ad0 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
28ae0 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
28af0 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
28b00 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
28b10 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
28b20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28b30 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
28b40 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
28b50 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
28b60 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
28b70 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
28b80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28b90 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
28ba0 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
28bb0 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
28bc0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
28bd0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
28be0 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
28bf0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
28c00 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
28c10 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28c20 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
28c30 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
28c40 72 65 5f 76 33 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v3()]..** <li
28c50 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
28c60 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
28c70 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
28c80 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
28c90 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
28ca0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
28cb0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
28cc0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
28cd0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
28ce0 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
28cf0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28d00 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
28d10 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
28d20 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
28d30 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
28d40 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
28d50 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
28d60 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
28d70 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
28d80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
28d90 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
28da0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28db0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
28dc0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
28dd0 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
28de0 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
28df0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
28e00 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
28e10 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
28e20 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
28e30 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
28e40 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
28e50 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
28e60 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
28e70 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
28e80 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
28e90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28ea0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
28eb0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
28ec0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
28ed0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
28ee0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
28ef0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
28f00 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
28f10 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
28f20 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
28f30 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
28f40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
28f50 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
28f60 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
28f70 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
28f80 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
28f90 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
28fa0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
28fb0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
28fc0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
28fd0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
28fe0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
28ff0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
29000 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
29010 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
29020 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
29030 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
29040 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
29050 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
29060 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
29070 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
29080 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
29090 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
290a0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
290b0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
290c0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
290d0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
290e0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
290f0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
29100 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
29110 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
29120 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
29130 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
29140 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
29150 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
29160 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
29170 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
29180 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
29190 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
291a0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
291b0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
291c0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
291d0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
291e0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
291f0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
29200 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
29210 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
29220 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
29230 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
29240 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
29250 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
29260 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
29270 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
29280 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
29290 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
292a0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
292b0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
292c0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
292d0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
292e0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
292f0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
29300 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
29310 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
29320 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
29330 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
29340 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
29350 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
29360 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
29370 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
29380 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
29390 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
293a0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
293b0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
293c0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
293d0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
293e0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
293f0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
29400 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
29410 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
29420 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
29430 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
29440 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
29450 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
29460 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
29470 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
29480 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
29490 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
294a0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
294b0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
294c0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
294d0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
294e0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
294f0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
29500 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
29510 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
29520 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
29530 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
29540 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
29550 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
29560 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
29570 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
29580 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
29590 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
295a0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
295b0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
295c0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
295d0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
295e0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
295f0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
29600 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
29610 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
29620 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
29630 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
29640 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
29650 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
29660 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
29670 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
29680 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29690 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
296a0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
296b0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
296c0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
296d0 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
296e0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
296f0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
29700 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
29710 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
29720 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
29730 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
29740 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
29750 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29760 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
29770 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
29780 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
29790 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
297a0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
297b0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
297c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
297d0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
297e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
297f0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
29800 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29810 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
29820 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
29830 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
29840 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29850 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
29860 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
29870 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
29880 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29890 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
298a0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
298b0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
298c0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
298d0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
298e0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
298f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
29900 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
29910 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
29920 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
29930 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29940 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
29950 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
29960 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
29970 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
29980 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29990 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
299a0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
299b0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
299c0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
299d0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
299e0 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
299f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
29a00 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
29a10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29a20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
29a30 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
29a40 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
29a50 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
29a60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29a70 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
29a80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
29a90 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
29aa0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29ab0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
29ac0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
29ad0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
29ae0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
29af0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
29b00 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c  tement.  If [sql
29b10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
29b20 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75  )] or.** the equ
29b30 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f  ivalent tries to
29b40 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20   allocate space 
29b50 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  for more than th
29b60 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a  is many opcodes.
29b70 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70  ** in a single p
29b80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29b90 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d  t, an SQLITE_NOM
29ba0 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  EM error is retu
29bb0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
29bc0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29bd0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
29be0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29bf0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
29c00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29c10 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29c20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
29c30 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
29c40 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29c50 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
29c60 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29c70 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
29c80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29c90 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29ca0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
29cb0 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
29cc0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
29cd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
29ce0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
29cf0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
29d00 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
29d10 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
29d20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29d30 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
29d40 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
29d50 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
29d60 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
29d70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
29d80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29d90 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
29da0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
29db0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29dc0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
29dd0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29de0 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
29df0 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
29e00 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
29e10 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
29e20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29e30 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
29e40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29e50 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
29e60 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29e70 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
29e80 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
29e90 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
29ea0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29eb0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
29ec0 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
29ed0 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
29ee0 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
29ef0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29f00 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
29f10 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
29f20 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
29f30 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
29f40 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
29f50 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
29f60 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
29f70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
29f80 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
29f90 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
29fa0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
29fb0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
29fc0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
29fd0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29fe0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
29ff0 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
2a000 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a010 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
2a020 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
2a030 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a040 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2a050 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
2a060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a070 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
2a080 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
2a090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a0a0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2a0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
2a0c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a0d0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
2a0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
2a0f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a100 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2a110 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
2a120 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
2a130 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2a140 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
2a150 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
2a160 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2a170 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2a180 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
2a190 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2a1a0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
2a1b0 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
2a1c0 33 52 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c  3REF: Prepare Fl
2a1d0 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
2a1e0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
2a1f0 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73 20 74   various flags t
2a200 68 61 74 20 63 61 6e 20 62 65 20 70 61 73 73 65  hat can be passe
2a210 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46  d into.** "prepF
2a220 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65 72 20  lags" parameter 
2a230 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2a240 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 61 6e  prepare_v3()] an
2a250 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  d.** [sqlite3_pr
2a260 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e  epare16_v3()] in
2a270 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  terfaces..**.** 
2a280 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20 62 65  New flags may be
2a290 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
2a2a0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
2a2b0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ite..**.** <dl>.
2a2c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50  ** [[SQLITE_PREP
2a2d0 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d  ARE_PERSISTENT]]
2a2e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52   ^(<dt>SQLITE_PR
2a2f0 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2a300 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a310 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2a320 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61 67 20  PERSISTENT flag 
2a330 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
2a340 70 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a  prepare_v3()].**
2a350 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2a360 65 70 61 72 65 31 36 5f 76 33 28 29 5d 0a 2a 2a  epare16_v3()].**
2a370 20 74 6f 20 6f 70 74 69 6d 69 7a 65 20 74 68 65   to optimize the
2a380 20 72 65 73 75 6c 74 69 6e 67 20 70 72 65 70 61   resulting prepa
2a390 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  red statement to
2a3a0 20 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72   be retained for
2a3b0 20 61 20 0a 2a 2a 20 72 65 6c 61 74 69 76 65 6c   a .** relativel
2a3c0 79 20 6c 6f 6e 67 20 61 6d 6f 75 6e 74 20 6f 66  y long amount of
2a3d0 20 74 69 6d 65 2e 29 5e 20 20 5e 57 69 74 68 6f   time.)^  ^Witho
2a3e0 75 74 20 74 68 69 73 20 66 6c 61 67 2c 0a 2a 2a  ut this flag,.**
2a3f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a400 65 5f 76 33 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v3()] and [sql
2a410 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a420 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61 74  3()] assume that
2a430 0a 2a 2a 20 74 68 65 20 70 72 65 70 61 72 65 64  .** the prepared
2a440 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2a450 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63  be used just onc
2a460 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66  e or at most a f
2a470 65 77 20 74 69 6d 65 73 0a 2a 2a 20 61 6e 64 20  ew times.** and 
2a480 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75  then destroyed u
2a490 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2a4a0 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69  nalize()] relati
2a4b0 76 65 6c 79 20 73 6f 6f 6e 2e 0a 2a 2a 20 3c 2f  vely soon..** </
2a4c0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
2a4d0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2a4e0 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20  RSISTENT        
2a4f0 20 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a        0x01../*.*
2a500 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
2a510 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
2a520 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
2a530 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
2a540 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20  nt compiler}.** 
2a550 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
2a560 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
2a570 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2a580 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
2a590 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2a5a0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
2a5b0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
2a5c0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
2a5d0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
2a5e0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2a5f0 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72  s.  Or, in other
2a600 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f   words, these ro
2a610 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f  utines.** are co
2a620 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74  nstructors for t
2a630 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2a640 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
2a650 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72  **.** The prefer
2a660 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75  red routine to u
2a670 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70  se is [sqlite3_p
2a680 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54  repare_v2()].  T
2a690 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
2a6a0 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66  repare()] interf
2a6b0 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e  ace is legacy an
2a6c0 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  d should be avoi
2a6d0 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ded..** [sqlite3
2a6e0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68  _prepare_v3()] h
2a6f0 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 65  as an extra "pre
2a700 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74  pFlags" option t
2a710 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66  hat is used.** f
2a720 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f  or special purpo
2a730 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ses..**.** The u
2a740 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20  se of the UTF-8 
2a750 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 72  interfaces is pr
2a760 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69  eferred, as SQLi
2a770 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  te currently.** 
2a780 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67  does all parsing
2a790 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54   using UTF-8.  T
2a7a0 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66  he UTF-16 interf
2a7b0 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
2a7c0 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e  d.** as a conven
2a7d0 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d  ience.  The UTF-
2a7e0 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  16 interfaces wo
2a7f0 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67  rk by converting
2a800 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65   the.** input te
2a810 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74  xt into UTF-8, t
2a820 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hen invoking the
2a830 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55   corresponding U
2a840 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a  TF-8 interface..
2a850 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2a860 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
2a870 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
2a880 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
2a890 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
2a8a0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
2a8b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a8c0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2a8d0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
2a8e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
2a8f0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
2a900 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a910 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2a920 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
2a930 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2a940 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
2a950 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
2a960 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
2a970 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
2a980 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
2a990 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
2a9a0 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c  3_prepare(), sql
2a9b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a9c0 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2a9d0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a  3_prepare_v3().*
2a9e0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
2a9f0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
2aa00 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c  te3_prepare16(),
2aa10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2aa20 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2aa30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2aa40 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 31  6_v3() use UTF-1
2aa50 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
2aa60 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
2aa70 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2aa80 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
2aa90 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
2aaa0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2aab0 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
2aac0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
2aad0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
2aae0 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
2aaf0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
2ab00 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
2ab10 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
2ab20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
2ab30 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
2ab40 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
2ab50 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
2ab60 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
2ab70 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
2ab80 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
2ab90 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
2aba0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
2abb0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
2abc0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
2abd0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2abe0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2abf0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
2ac00 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
2ac10 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
2ac20 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
2ac30 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
2ac40 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
2ac50 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2ac60 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
2ac70 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
2ac80 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
2ac90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2aca0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
2acb0 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
2acc0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
2acd0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
2ace0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
2acf0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ad00 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
2ad10 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
2ad20 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
2ad30 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2ad40 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
2ad50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ad60 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
2ad70 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
2ad80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ad90 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
2ada0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
2adb0 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
2adc0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
2add0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
2ade0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
2adf0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
2ae00 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
2ae10 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
2ae20 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
2ae30 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
2ae40 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
2ae50 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
2ae60 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
2ae70 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
2ae80 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
2ae90 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2aea0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
2aeb0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2aec0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
2aed0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
2aee0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
2aef0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
2af00 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
2af10 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
2af20 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
2af30 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
2af40 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2af50 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2af60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2af70 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74  pare_v2(), sqlit
2af80 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c  e3_prepare_v3(),
2af90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2afa0 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2afb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2afc0 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 65  6_v3() interface
2afd0 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65  s are recommende
2afe0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
2aff0 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f  ograms..** The o
2b000 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2b010 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  (sqlite3_prepare
2b020 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
2b030 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61  repare16()).** a
2b040 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
2b050 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2b060 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
2b070 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
2b080 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
2b090 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  e "vX" interface
2b0a0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
2b0b0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
2b0c0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
2b0d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2b0e0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
2b0f0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2b100 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2b110 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
2b120 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
2b130 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
2b140 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
2b150 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
2b160 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
2b170 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
2b180 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
2b190 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
2b1a0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
2b1b0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
2b1c0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
2b1d0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
2b1e0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2b1f0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
2b200 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
2b210 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
2b220 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
2b230 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
2b240 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
2b250 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
2b260 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
2b270 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
2b280 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
2b290 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
2b2a0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
2b2b0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2b2c0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
2b2d0 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
2b2e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2b2f0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
2b300 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
2b310 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
2b320 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2b330 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
2b340 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
2b350 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
2b360 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
2b370 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
2b380 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
2b390 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
2b3a0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
2b3b0 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
2b3c0 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
2b3d0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
2b3e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
2b3f0 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
2b400 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
2b410 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
2b420 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
2b430 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
2b440 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
2b450 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
2b460 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
2b470 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
2b480 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
2b490 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2b4a0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2b4b0 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
2b4c0 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
2b4d0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
2b4e0 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
2b4f0 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
2b500 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
2b510 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2b520 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
2b530 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
2b540 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
2b550 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2b560 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
2b570 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
2b580 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
2b590 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
2b5a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b5b0 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
2b5c0 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
2b5d0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
2b5e0 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
2b5f0 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
2b600 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
2b610 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2b620 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
2b630 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
2b640 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2b650 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
2b660 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
2b670 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
2b680 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
2b690 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
2b6a0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
2b6b0 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
2b6c0 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
2b6d0 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
2b6e0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
2b6f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
2b700 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
2b710 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
2b720 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
2b730 69 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c  i>.**.** <p>^sql
2b740 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2b750 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20 73  ) differs from s
2b760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b770 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69  2() only in havi
2b780 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 20  ng.** the extra 
2b790 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65  prepFlags parame
2b7a0 74 65 72 2c 20 77 68 69 63 68 20 69 73 20 61 20  ter, which is a 
2b7b0 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69 73  bit array consis
2b7c0 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a  ting of zero or.
2b7d0 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
2b7e0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2b7f0 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 45  ERSISTENT|SQLITE
2b800 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67  _PREPARE_*] flag
2b810 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  s.  ^The.** sqli
2b820 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2b830 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
2b840 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
2b850 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
2b860 70 72 65 70 61 72 65 5f 76 33 28 29 20 77 69 74  prepare_v3() wit
2b870 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c 61  h a zero prepFla
2b880 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  gs parameter..**
2b890 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
2b8a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
2b8b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2b8c0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2b8d0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2b8e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2b8f0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2b900 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2b910 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2b920 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2b930 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2b940 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2b950 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2b960 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2b970 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2b980 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2b990 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2b9a0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2b9b0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2b9c0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2b9d0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2b9e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b9f0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2ba00 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2ba10 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2ba20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2ba30 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2ba40 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2ba50 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2ba60 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2ba70 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2ba80 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2ba90 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2baa0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2bab0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2bac0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2bad0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2bae0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2baf0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2bb00 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2bb10 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2bb20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2bb30 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c  repare_v3(.  sql
2bb40 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2bb50 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2bb60 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2bb70 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2bb80 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2bb90 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2bba0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2bbb0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2bbc0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2bbd0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2bbe0 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67  ytes. */.  unsig
2bbf0 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67  ned int prepFlag
2bc00 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f  s, /* Zero or mo
2bc10 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  re SQLITE_PREPAR
2bc20 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71  E_ flags */.  sq
2bc30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2bc40 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2bc50 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2bc60 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2bc70 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2bc80 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2bc90 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2bca0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2bcb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bcc0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2bcd0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2bce0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2bcf0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2bd00 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2bd10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2bd20 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2bd30 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2bd40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2bd50 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2bd60 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2bd70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2bd80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2bd90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2bda0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2bdb0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2bdc0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2bdd0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2bde0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2bdf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2be00 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2be10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2be20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2be30 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2be40 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2be50 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2be60 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2be70 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2be80 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2be90 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2bea0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2beb0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2bec0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2bed0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2bee0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2bef0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2bf00 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2bf10 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2bf20 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2bf30 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2bf40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2bf50 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2bf60 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2bf70 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2bf80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2bf90 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2bfa0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2bfb0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2bfc0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2bfd0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2bfe0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2bff0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2c000 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69   */.  unsigned i
2c010 6e 74 20 70 72 65 70 46 61 6c 67 73 2c 20 2f 2a  nt prepFalgs, /*
2c020 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51   Zero or more SQ
2c030 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c  LITE_PREPARE_ fl
2c040 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  ags */.  sqlite3
2c050 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2c060 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2c070 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2c080 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2c090 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2c0a0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2c0b0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2c0c0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2c0d0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2c0e0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2c0f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c100 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c110 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2c120 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2c130 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c140 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2c150 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2c160 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2c170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c180 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2c190 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b  .** created by [
2c1a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c1b0 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2c1c0 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a  prepare_v3()],.*
2c1d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c1e0 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
2c1f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c200 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  6_v3()]..** ^The
2c210 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2c220 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2c230 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2c240 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2c250 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2c260 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78  ning the SQL tex
2c270 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74  t of prepared st
2c280 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a  atement P with.*
2c290 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  * [bound paramet
2c2a0 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a  ers] expanded..*
2c2b0 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2c2c0 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65  le, if a prepare
2c2d0 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
2c2e0 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
2c2f0 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45   SQL.** text "SE
2c300 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2c310 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72  and if parameter
2c320 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74   $abc is bound t
2c330 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a  o integer 2345.*
2c340 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * and parameter 
2c350 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c  :xyz is unbound,
2c360 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71   then sqlite3_sq
2c370 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  l() will return.
2c380 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
2c390 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20  string, "SELECT 
2c3a0 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73  $abc,:xyz" but s
2c3b0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2c3c0 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  sql().** will re
2c3d0 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34  turn "SELECT 234
2c3e0 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a  5,NULL".)^.**.**
2c3f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2c400 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74  panded_sql() int
2c410 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
2c420 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
2c430 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  ent memory.** is
2c440 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f   available to ho
2c450 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f  ld the result, o
2c460 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20  r if the result 
2c470 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
2c480 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  .** the maximum 
2c490 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65  string length de
2c4a0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2c4b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2c4c0 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  NGTH]..**.** ^Th
2c4d0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
2c4e0 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
2c4f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2c500 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20  limits the size 
2c510 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61  of.** bound para
2c520 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73  meter expansions
2c530 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
2c540 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70  OMIT_TRACE] comp
2c550 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
2c560 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65  on causes sqlite
2c570 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2c580 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72   to always retur
2c590 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n NULL..**.** ^T
2c5a0 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2c5b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71  ed by sqlite3_sq
2c5c0 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20  l(P) is managed 
2c5d0 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73  by SQLite and is
2c5e0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
2c5f0 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65  y freed when the
2c600 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2c610 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2c620 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67  ..** ^The string
2c630 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2c640 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2c650 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68  l(P), on the oth
2c660 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f  er hand,.** is o
2c670 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2c680 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2c690 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65  and must be free
2c6a0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2c6b0 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e  ion.** by passin
2c6c0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
2c6d0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  _free()]..*/.con
2c6e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2c6f0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2c700 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20  t *pStmt);.char 
2c710 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  *sqlite3_expande
2c720 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  d_sql(sqlite3_st
2c730 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2c740 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2c750 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
2c760 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
2c770 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
2c780 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c790 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2c7a0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2c7b0 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
2c7c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2c7d0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
2c7e0 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
2c7f0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c800 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
2c810 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
2c820 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
2c830 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2c840 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
2c850 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
2c860 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2c870 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
2c880 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
2c890 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
2c8a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
2c8b0 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
2c8c0 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
2c8d0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2c8e0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
2c8f0 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
2c900 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
2c910 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
2c920 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
2c930 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
2c940 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
2c950 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
2c960 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2c970 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
2c980 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
2c990 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2c9a0 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
2c9b0 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
2c9c0 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
2c9d0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
2c9e0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
2c9f0 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
2ca00 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
2ca10 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2ca20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
2ca30 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
2ca40 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2ca50 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
2ca60 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
2ca70 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
2ca80 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
2ca90 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
2caa0 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
2cab0 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
2cac0 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
2cad0 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
2cae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2caf0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2cb00 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
2cb10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
2cb20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
2cb30 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
2cb40 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
2cb50 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
2cb60 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
2cb70 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
2cb80 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
2cb90 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
2cba0 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
2cbb0 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
2cbc0 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
2cbd0 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
2cbe0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2cbf0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2cc00 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
2cc10 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
2cc20 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
2cc30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
2cc40 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2cc50 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
2cc60 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
2cc70 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
2cc80 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2cc90 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
2cca0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2ccb0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2ccc0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2ccd0 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45  rns true for [BE
2cce0 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42  GIN] since.** [B
2ccf0 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74  EGIN] merely set
2cd00 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73  s internal flags
2cd10 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e  , but the [BEGIN
2cd20 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45  |BEGIN IMMEDIATE
2cd30 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c  ] and.** [BEGIN|
2cd40 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d  BEGIN EXCLUSIVE]
2cd50 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75   commands do tou
2cd60 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
2cd70 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65  and so.** sqlite
2cd80 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2cd90 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  ) returns false 
2cda0 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e  for those comman
2cdb0 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
2cdc0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2cdd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2cde0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2cdf0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2ce00 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
2ce10 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
2ce20 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48  en Reset.** METH
2ce30 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ce40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ce50 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2ce60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ce70 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2ce80 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
2ce90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cea0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
2ceb0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
2cec0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
2ced0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
2cee0 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72  ut has neither r
2cef0 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
2cf00 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53   (returned.** [S
2cf10 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d  QLITE_DONE] from
2cf20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2cf30 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20  )]) nor.** been 
2cf40 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
2cf50 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
2cf60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2cf70 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
2cf80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2cf90 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
2cfa0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
2cfb0 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
2cfc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2cfd0 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
2cfe0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
2cff0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d000 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
2d010 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2d020 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2d030 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
2d040 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
2d050 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2d060 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
2d070 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
2d080 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
2d090 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
2d0a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d0b0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2d0c0 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
2d0d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2d0e0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
2d0f0 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
2d100 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
2d110 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
2d120 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
2d130 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
2d140 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
2d150 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
2d160 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
2d170 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
2d180 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2d190 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
2d1a0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2d1b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
2d1c0 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
2d1d0 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
2d1e0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
2d1f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d200 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
2d210 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
2d220 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
2d230 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
2d240 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
2d250 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
2d260 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2d270 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
2d280 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
2d290 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2d2a0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
2d2b0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
2d2c0 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
2d2d0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
2d2e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
2d2f0 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
2d300 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2d310 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
2d320 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
2d330 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
2d340 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
2d350 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
2d360 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
2d370 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
2d380 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
2d390 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
2d3a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2d3b0 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
2d3c0 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
2d3d0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
2d3e0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
2d3f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d400 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
2d410 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
2d420 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
2d430 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
2d440 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
2d450 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
2d460 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
2d470 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2d480 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
2d490 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69  3_value_dup()] i
2d4a0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2d4b0 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63  used to construc
2d4c0 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74  t a new .** prot
2d4d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d4e0 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72  lue from an unpr
2d4f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d500 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
2d510 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
2d520 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
2d530 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
2d540 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
2d550 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
2d560 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
2d570 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
2d580 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
2d590 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2d5a0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
2d5b0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
2d5c0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2d5d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2d5e0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
2d5f0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
2d600 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
2d610 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
2d620 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
2d630 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
2d640 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
2d650 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
2d660 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
2d670 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
2d680 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
2d690 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
2d6a0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
2d6b0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
2d6c0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
2d6d0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
2d6e0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
2d6f0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
2d700 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
2d710 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2d720 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
2d730 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
2d740 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
2d750 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
2d760 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
2d770 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
2d780 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2d790 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
2d7a0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
2d7b0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
2d7c0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
2d7d0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
2d7e0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2d7f0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
2d800 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
2d810 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
2d820 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
2d830 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
2d840 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
2d850 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
2d860 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
2d870 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
2d880 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2d890 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
2d8a0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
2d8b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2d8c0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2d8d0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2d8e0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2d8f0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
2d900 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
2d910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2d920 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
2d930 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
2d940 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2d950 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2d960 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2d970 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2d980 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
2d990 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2d9a0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
2d9b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
2d9c0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
2d9d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2d9e0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
2d9f0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2da00 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
2da10 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2da20 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2da30 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2da40 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2da50 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2da60 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2da70 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2da80 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2da90 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2daa0 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2dab0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2dac0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2dad0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2dae0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2daf0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2db00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2db10 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2db20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2db30 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2db40 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2db50 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2db60 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2db70 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2db80 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2db90 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2dba0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2dbb0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2dbc0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2dbd0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2dbe0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2dbf0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2dc00 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2dc10 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2dc20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2dc30 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2dc40 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2dc50 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2dc60 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2dc70 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2dc80 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2dc90 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2dca0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2dcb0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2dcc0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2dcd0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2dce0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2dcf0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2dd00 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2dd10 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2dd20 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2dd30 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2dd40 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2dd50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2dd60 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2dd70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2dd80 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2dd90 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2dda0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2ddb0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2ddc0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2ddd0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2dde0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2ddf0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2de00 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2de10 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2de20 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2de30 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2de40 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2de50 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2de60 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2de70 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2de80 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2de90 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2dea0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2deb0 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2dec0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2ded0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2dee0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2def0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2df00 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2df10 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2df20 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2df30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2df40 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2df50 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2df60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2df70 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2df80 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2df90 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2dfa0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2dfb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2dfc0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2dfd0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2dfe0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f  _prepare_v3()] o
2dff0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2e000 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2e010 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2e020 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2e030 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2e040 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2e050 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2e060 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2e070 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2e080 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2e090 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2e0a0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2e0b0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2e0c0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2e0d0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2e0e0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2e0f0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2e100 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2e110 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2e120 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2e130 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2e140 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2e150 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e160 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2e170 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2e180 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2e190 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2e1a0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2e1b0 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2e1c0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2e1d0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2e1e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2e1f0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2e200 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2e210 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2e220 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2e230 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2e240 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2e250 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2e260 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2e270 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2e280 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2e290 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2e2a0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2e2b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2e2c0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2e2d0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2e2e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2e2f0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2e300 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2e310 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2e320 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2e330 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2e340 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2e350 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2e360 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2e370 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2e380 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2e390 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2e3a0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2e3b0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2e3c0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2e3d0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2e3e0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2e3f0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2e400 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2e410 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2e420 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2e430 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2e440 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e450 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2e460 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2e470 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2e480 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2e490 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2e4a0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2e4b0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2e4c0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2e4d0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2e4e0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2e4f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2e500 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2e510 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2e520 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2e530 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2e540 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2e550 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2e560 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2e570 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2e580 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2e590 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
2e5a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e5b0 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
2e5c0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2e5d0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2e5e0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2e5f0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2e600 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2e610 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2e620 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2e630 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2e640 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2e650 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2e660 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2e670 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2e680 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2e690 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2e6a0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2e6b0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2e6c0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2e6d0 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2e6e0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2e6f0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2e700 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2e710 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2e720 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2e730 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2e740 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
2e750 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2e760 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2e770 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2e780 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2e790 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2e7a0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2e7b0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2e7c0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2e7d0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2e7e0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2e7f0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2e800 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2e810 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2e820 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2e830 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2e840 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2e850 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2e860 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2e870 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2e880 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2e890 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2e8a0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2e8b0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2e8c0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2e8d0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2e8e0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2e8f0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2e900 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2e910 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2e920 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2e930 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2e940 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2e950 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2e960 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2e970 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2e980 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2e990 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2e9a0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2e9b0 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2e9c0 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2e9d0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2e9e0 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2e9f0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2ea00 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2ea10 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2ea20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2ea30 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2ea40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2ea50 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2ea60 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2ea70 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2ea80 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2ea90 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2eaa0 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2eab0 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2eac0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2ead0 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2eae0 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2eaf0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2eb00 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2eb10 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2eb20 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2eb30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2eb40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2eb50 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2eb60 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2eb70 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2eb80 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2eb90 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2eba0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2ebb0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2ebc0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2ebd0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2ebe0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2ebf0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2ec00 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2ec10 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2ec20 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2ec30 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2ec40 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2ec50 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2ec60 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2ec70 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2ec80 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2ec90 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2eca0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2ecb0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2ecc0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2ecd0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2ece0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
2ecf0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2ed00 6f 69 6e 74 65 72 28 53 2c 49 2c 50 29 20 72 6f  ointer(S,I,P) ro
2ed10 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68 65  utine causes the
2ed20 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   I-th parameter 
2ed30 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  in.** [prepared 
2ed40 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20  statement] S to 
2ed50 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75  have an SQL valu
2ed60 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74  e of NULL, but t
2ed70 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73  o also be.** ass
2ed80 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2ed90 20 70 6f 69 6e 74 65 72 20 50 2e 0a 2a 2a 20 5e   pointer P..** ^
2eda0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2edb0 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74 69  _pointer() routi
2edc0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2edd0 6f 20 70 61 73 73 0a 2a 2a 20 68 6f 73 74 2d 6c  o pass.** host-l
2ede0 61 6e 67 75 61 67 65 20 70 6f 69 6e 74 65 72 73  anguage pointers
2edf0 20 69 6e 74 6f 20 5b 61 70 70 6c 69 63 61 74 69   into [applicati
2ee00 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2ee10 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 5e 41  unctions]..** ^A
2ee20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
2ee30 69 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  is initialized u
2ee40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 69  sing [sqlite3_bi
2ee50 6e 64 5f 70 6f 69 6e 74 65 72 28 29 5d 20 61 70  nd_pointer()] ap
2ee60 70 65 61 72 73 0a 2a 2a 20 74 6f 20 62 65 20 61  pears.** to be a
2ee70 6e 20 6f 72 64 69 6e 61 72 79 20 53 51 4c 20 4e  n ordinary SQL N
2ee80 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 65 76 65  ULL value to eve
2ee90 72 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  rything other th
2eea0 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  an.** [sqlite3_v
2eeb0 61 6c 75 65 5f 70 6f 69 6e 74 65 72 28 29 5d 2e  alue_pointer()].
2eec0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2eed0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2eee0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2eef0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2ef00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2ef10 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2ef20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2ef30 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2ef40 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2ef50 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2ef60 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2ef70 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2ef80 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2ef90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2efa0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2efb0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2efc0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2efd0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2efe0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2eff0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2f000 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f010 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2f020 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2f030 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2f040 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2f050 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2f060 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2f070 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2f080 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2f090 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2f0a0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2f0b0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2f0c0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2f0d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f0e0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2f0f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f100 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2f110 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2f120 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2f130 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2f140 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2f150 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2f160 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2f170 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2f180 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2f190 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2f1a0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2f1b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2f1c0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2f1d0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2f1e0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2f1f0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2f200 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2f210 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2f220 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2f230 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2f240 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2f250 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2f260 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2f270 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2f280 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2f290 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2f2a0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2f2b0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2f2c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2f2d0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2f2e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f2f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f300 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2f310 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2f320 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2f330 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2f340 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2f350 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2f360 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2f370 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2f380 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2f390 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2f3a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
2f3b0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2f3c0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
2f3d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2f3e0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2f3f0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2f400 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2f410 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2f420 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2f430 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
2f440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2f450 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f460 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2f470 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2f480 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2f490 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2f4a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2f4b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2f4c0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2f4d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2f4e0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2f4f0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2f500 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2f510 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
2f520 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2f530 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
2f540 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2f550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f560 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
2f570 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
2f580 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
2f590 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2f5a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f5b0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
2f5c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2f5d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
2f5e0 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ter(sqlite3_stmt
2f5f0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 29 3b 0a  *, int, void*);.
2f600 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2f610 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2f620 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2f630 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t n);.int sqlite
2f640 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
2f650 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2f660 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
2f670 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2f680 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2f690 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2f6a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2f6b0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2f6c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2f6d0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2f6e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2f6f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2f700 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2f710 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2f720 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2f730 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2f740 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2f750 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2f760 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2f770 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2f780 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2f790 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2f7a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2f7b0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2f7c0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2f7d0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2f7e0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2f7f0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2f800 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2f810 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2f820 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2f830 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2f840 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2f850 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2f860 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2f870 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2f880 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2f890 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2f8a0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2f8b0 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2f8c0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2f8d0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2f8e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2f8f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2f900 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2f910 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2f920 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2f930 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2f940 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2f950 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2f960 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2f970 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2f980 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2f990 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2f9a0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2f9b0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2f9c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f9d0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2f9e0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f9f0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2fa00 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2fa10 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2fa20 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2fa30 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2fa40 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2fa50 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2fa60 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2fa70 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2fa80 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2fa90 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2faa0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2fab0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2fac0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2fad0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2fae0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2faf0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2fb00 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2fb10 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2fb20 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2fb30 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2fb40 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2fb50 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2fb60 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2fb70 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2fb80 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2fb90 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2fba0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2fbb0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2fbc0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2fbd0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2fbe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2fbf0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2fc00 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2fc10 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2fc20 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2fc30 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2fc40 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2fc50 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2fc60 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2fc70 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2fc80 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2fc90 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2fca0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2fcb0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2fcc0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2fcd0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2fce0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2fcf0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2fd00 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2fd10 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
2fd20 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f  epare16_v2()], o
2fd30 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2fd40 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v3()]..**.*
2fd50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2fd60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2fd70 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2fd80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2fd90 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2fda0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2fdb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2fdc0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2fdd0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *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 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
2fe00 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
2fe10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2fe20 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
2fe30 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
2fe40 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
2fe50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2fe60 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2fe70 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
2fe80 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
2fe90 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
2fea0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
2feb0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
2fec0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
2fed0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
2fee0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2fef0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2ff00 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
2ff10 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
2ff20 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
2ff30 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
2ff40 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
2ff50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
2ff60 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
2ff70 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
2ff80 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
2ff90 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
2ffa0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
2ffb0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
2ffc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ffd0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
2ffe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2fff0 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v3()]..**.** See
30000 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
30010 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30020 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
30030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30040 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
30050 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
30060 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
30070 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ame()]..*/.int s
30080 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30090 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
300a0 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
300b0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
300c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
300d0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
300e0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
300f0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
30100 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30110 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
30120 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
30130 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
30140 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
30150 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
30160 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
30170 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
30180 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
30190 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
301a0 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
301b0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
301c0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
301d0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
301e0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
301f0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
30200 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
30210 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
30220 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
30230 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
30240 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30250 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
30260 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
30270 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
30280 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
30290 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
302a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
302b0 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  . ^If this routi
302c0 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ne returns 0, th
302d0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a  at means the .**
302e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
302f0 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f  ment] returns no
30300 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
30310 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
30320 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75  .** ^However, ju
30330 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20  st because this 
30340 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30350 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65  a positive numbe
30360 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65  r does not.** me
30370 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d  an that one or m
30380 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61  ore rows of data
30390 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
303a0 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74  d.  ^A SELECT st
303b0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20  atement.** will 
303c0 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f  always have a po
303d0 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63  sitive sqlite3_c
303e0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75  olumn_count() bu
303f0 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  t depending on t
30400 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  he.** WHERE clau
30410 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  se constraints a
30420 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e  nd the table con
30430 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72  tent, it might r
30440 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a  eturn no rows..*
30450 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
30460 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
30470 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
30480 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
30490 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
304a0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
304b0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
304c0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
304d0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
304e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
304f0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
30500 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
30510 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
30520 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
30530 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
30540 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
30550 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
30560 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
30570 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
30580 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30590 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
305a0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
305b0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
305c0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
305d0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
305e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
305f0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
30600 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
30610 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
30620 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
30630 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
30640 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
30650 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
30660 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
30670 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
30680 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
30690 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
306a0 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
306b0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
306c0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
306d0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
306e0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
306f0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
30700 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
30710 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
30720 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
30730 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
30740 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
30750 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
30760 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
30770 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
30780 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
30790 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
307a0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
307b0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
307c0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
307d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
307e0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
307f0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
30800 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
30810 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
30820 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
30830 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
30840 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
30850 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
30860 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
30870 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
30880 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
30890 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
308a0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
308b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
308c0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
308d0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
308e0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
308f0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
30900 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
30910 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
30920 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
30930 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
30940 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
30950 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
30960 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
30970 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
30980 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
30990 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
309a0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
309b0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
309c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
309d0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
309e0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
309f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30a00 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
30a10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
30a20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30a30 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
30a40 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
30a50 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
30a60 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
30a70 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
30a80 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
30a90 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
30aa0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
30ab0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
30ac0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
30ad0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
30ae0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
30af0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
30b00 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
30b10 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
30b20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
30b30 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
30b40 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
30b50 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
30b60 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
30b70 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
30b80 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
30b90 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
30ba0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
30bb0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
30bc0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
30bd0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
30be0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
30bf0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
30c00 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
30c10 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
30c20 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
30c30 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
30c40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30c50 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
30c60 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
30c70 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
30c80 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
30c90 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
30ca0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
30cb0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
30cc0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
30cd0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
30ce0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
30cf0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
30d00 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
30d10 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
30d20 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
30d30 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
30d40 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
30d50 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
30d60 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
30d70 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
30d80 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
30d90 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
30da0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
30db0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
30dc0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
30dd0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
30de0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
30df0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
30e00 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
30e10 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
30e20 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
30e30 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
30e40 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
30e50 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
30e60 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
30e70 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
30e80 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
30e90 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
30ea0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
30eb0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
30ec0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
30ed0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
30ee0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
30ef0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
30f00 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
30f10 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
30f20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
30f30 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
30f40 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
30f50 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
30f60 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
30f70 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
30f80 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
30f90 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
30fa0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
30fb0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
30fc0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
30fd0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
30fe0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
30ff0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
31000 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
31010 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
31020 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
31030 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
31040 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
31050 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
31060 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
31070 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
31080 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
31090 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
310a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
310b0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
310c0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
310d0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
310e0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
310f0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
31100 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
31110 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
31120 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
31130 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
31140 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
31150 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
31160 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
31170 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
31180 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
31190 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
311a0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
311b0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
311c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
311d0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
311e0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
311f0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
31200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
31210 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
31220 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
31230 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
31240 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
31250 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
31260 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
31270 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
31280 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
31290 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
312a0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
312b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
312c0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
312d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
312e0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
312f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31300 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
31310 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
31320 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
31330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
31340 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
31350 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
31360 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
31370 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
31380 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
31390 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
313a0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
313b0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
313c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
313d0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
313e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
313f0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
31400 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
31410 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31420 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
31430 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
31440 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
31450 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31460 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
31470 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
31480 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31490 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
314a0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
314b0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
314c0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
314d0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
314e0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
314f0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
31500 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
31510 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
31520 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
31530 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
31540 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
31550 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
31560 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
31570 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
31580 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
31590 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
315a0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
315b0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
315c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
315d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
315e0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
315f0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
31600 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
31610 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
31620 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
31630 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
31640 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
31650 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
31660 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
31670 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
31680 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
31690 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
316a0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
316b0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
316c0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
316d0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
316e0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
316f0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
31700 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
31710 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
31720 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
31730 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
31740 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
31750 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
31760 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
31770 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
31780 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
31790 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
317a0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
317b0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
317c0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
317d0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
317e0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
317f0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
31800 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
31810 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
31820 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
31830 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
31840 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
31850 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
31860 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
31870 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
31880 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
31890 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
318a0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
318b0 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
318c0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
318d0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
318e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
318f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31900 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
31910 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
31920 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
31930 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
31940 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
31950 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
31960 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31970 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
31980 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
31990 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
319a0 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a   using any of.**
319b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
319c0 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
319d0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
319e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
319f0 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72  e16_v2()],.** or
31a00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31a10 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65  e16_v3()] or one
31a20 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
31a30 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
31a40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
31a50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
31a60 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
31a70 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
31a80 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
31a90 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
31aa0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
31ab0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
31ac0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
31ad0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
31ae0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
31af0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
31b00 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
31b10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
31b20 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
31b30 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20 69  the newer "vX" i
31b40 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71  nterfaces.** [sq
31b50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
31b60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
31b70 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
31b80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
31b90 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
31ba0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
31bb0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
31bc0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
31bd0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
31be0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
31bf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
31c00 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
31c10 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20  the.** new "vX" 
31c20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
31c30 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
31c40 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
31c50 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
31c60 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
31c70 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
31c80 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
31c90 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
31ca0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
31cb0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
31cc0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
31cd0 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
31ce0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
31cf0 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
31d00 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
31d10 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
31d20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
31d30 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
31d40 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
31d50 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
31d60 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
31d70 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
31d80 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
31d90 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
31da0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
31db0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
31dc0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
31dd0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
31de0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
31df0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
31e00 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
31e10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31e20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
31e30 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
31e40 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
31e50 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
31e60 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
31e70 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
31e80 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
31e90 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
31ea0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
31eb0 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
31ec0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
31ed0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
31ee0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
31ef0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
31f00 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
31f10 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
31f20 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
31f30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
31f40 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
31f50 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
31f60 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
31f70 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
31f80 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
31f90 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
31fa0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
31fb0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
31fc0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
31fd0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
31fe0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
31ff0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
32000 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
32010 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
32020 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
32030 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
32040 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
32050 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
32060 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
32070 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
32080 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
32090 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
320a0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
320b0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
320c0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
320d0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
320e0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
320f0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
32100 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
32110 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
32120 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
32130 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
32140 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
32150 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
32160 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
32170 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
32180 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
32190 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
321a0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
321b0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
321c0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
321d0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
321e0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
321f0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
32200 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
32210 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
32220 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
32230 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
32240 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
32250 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
32260 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
32270 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
32280 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
32290 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
322a0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
322b0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
322c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
322d0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
322e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
322f0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
32300 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
32310 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
32320 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
32330 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
32340 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
32350 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
32360 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
32370 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
32380 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
32390 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
323a0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
323b0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
323c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
323d0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
323e0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
323f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
32400 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
32410 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
32420 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
32430 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
32440 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
32450 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
32460 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
32470 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
32480 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
32490 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
324a0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
324b0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
324c0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
324d0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
324e0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
324f0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
32500 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
32510 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
32520 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
32530 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
32540 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
32550 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
32560 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
32570 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
32580 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
32590 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
325a0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
325b0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
325c0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
325d0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
325e0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
325f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32600 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
32610 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
32620 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
32630 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
32640 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b  ().  But after [
32650 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
32660 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32  ] ([dateof:3.6.2
32670 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  3.1],.** sqlite3
32680 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
32690 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
326a0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
326b0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
326c0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
326d0 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
326e0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
326f0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
32700 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
32710 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
32720 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
32730 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
32740 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
32750 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
32760 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
32770 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
32780 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
32790 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
327a0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
327b0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
327c0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
327d0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
327e0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
327f0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
32800 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
32810 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
32820 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
32830 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
32840 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
32850 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
32860 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
32870 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
32880 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
32890 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
328a0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
328b0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
328c0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
328d0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
328e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
328f0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
32900 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
32910 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
32920 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
32930 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
32940 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
32950 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
32960 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
32970 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
32980 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
32990 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
329a0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
329b0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
329c0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
329d0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
329e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
329f0 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v3()] or [sqlit
32a00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
32a10 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
32a20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
32a30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
32a40 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74  are16_v3()] inst
32a50 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
32a60 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
32a70 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
32a80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
32a90 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
32aa0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
32ab0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
32ac0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
32ad0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
32ae0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
32af0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
32b00 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
32b10 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  es is recommende
32b20 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
32b30 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
32b40 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
32b50 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
32b60 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
32b70 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54  esult set.** MET
32b80 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
32b90 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
32ba0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
32bb0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
32bc0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
32bd0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
32be0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
32bf0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
32c00 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
32c10 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
32c20 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
32c30 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
32c40 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
32c50 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
32c60 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
32c70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
32c80 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
32c90 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
32ca0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
32cb0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
32cc0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
32cd0 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
32ce0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
32cf0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
32d00 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
32d10 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
32d20 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
32d30 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
32d40 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
32d50 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
32d60 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
32d70 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
32d80 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
32d90 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
32da0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
32db0 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
32dc0 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
32dd0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
32de0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
32df0 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
32e00 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
32e10 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
32e20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
32e30 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
32e40 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
32e50 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
32e60 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
32e70 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
32e80 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
32e90 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
32ea0 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
32eb0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
32ec0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
32ed0 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
32ee0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
32ef0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
32f00 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32f10 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
32f20 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
32f30 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
32f40 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
32f50 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
32f60 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
32f70 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
32f80 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
32f90 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
32fa0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
32fb0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
32fc0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
32fd0 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
32fe0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
32ff0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
33000 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
33010 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
33020 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
33030 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
33040 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
33050 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
33060 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
33070 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
33080 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
33090 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
330a0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
330b0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
330c0 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
330d0 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
330e0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
330f0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
33100 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
33110 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
33120 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
33130 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
33140 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
33150 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
33160 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
33170 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
33180 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
33190 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
331a0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
331b0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
331c0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
331d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
331e0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
331f0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
33200 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
33210 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
33220 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
33230 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
33240 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
33250 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
33260 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
33270 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d  mt.**.** <b>Summ
33280 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f  ary:</b>.** <blo
33290 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62  ckquote><table b
332a0 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64  order=0 cellpadd
332b0 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e  ing=0 cellspacin
332c0 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  g=0>.** <tr><td>
332d0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
332e0 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72  n_blob</b><td>&r
332f0 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73  arr;<td>BLOB res
33300 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
33310 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
33320 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26  _double</b><td>&
33330 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65  rarr;<td>REAL re
33340 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
33350 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
33360 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  n_int</b><td>&ra
33370 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e  rr;<td>32-bit IN
33380 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20  TEGER result.** 
33390 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
333a0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c  e3_column_int64<
333b0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
333c0 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20  >64-bit INTEGER 
333d0 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
333e0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
333f0 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e  umn_text</b><td>
33400 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20  &rarr;<td>UTF-8 
33410 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  TEXT result.** <
33420 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
33430 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c  3_column_text16<
33440 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
33450 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 65 73  >UTF-16 TEXT res
33460 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
33470 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
33480 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72  _value</b><td>&r
33490 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75  arr;<td>The resu
334a0 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71  lt as an .** [sq
334b0 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72  lite3_value|unpr
334c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
334d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
334e0 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b  * <tr><td>&nbsp;
334f0 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e  <td>&nbsp;<td>&n
33500 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  bsp;.** <tr><td>
33510 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
33520 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26  n_bytes</b><td>&
33530 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  rarr;<td>Size of
33540 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20   a BLOB.** or a 
33550 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c  UTF-8 TEXT resul
33560 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74  t in bytes.** <t
33570 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
33580 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26  _column_bytes16&
33590 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a  nbsp;&nbsp;</b>.
335a0 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62  ** <td>&rarr;&nb
335b0 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a  sp;&nbsp;<td>Siz
335c0 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54  e of UTF-16.** T
335d0 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20  EXT in bytes.** 
335e0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
335f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f  e3_column_type</
33600 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
33610 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74  Default.** datat
33620 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
33630 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62  t.** </table></b
33640 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
33650 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e   <b>Details:</b>
33660 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
33670 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
33680 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
33690 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
336a0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
336b0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
336c0 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
336d0 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
336e0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
336f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
33700 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
33710 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
33720 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
33730 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
33740 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
33750 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
33760 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33770 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v3()] or one of 
33780 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
33790 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
337a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
337b0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
337c0 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
337d0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
337e0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
337f0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
33800 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
33810 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
33820 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
33830 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
33840 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
33850 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
33860 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
33870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
33880 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
33890 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
338a0 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
338b0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
338c0 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
338d0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
338e0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
338f0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
33900 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
33910 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
33920 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
33930 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
33940 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
33950 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
33960 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
33970 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
33980 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
33990 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
339a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
339b0 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
339c0 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
339d0 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
339e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
339f0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
33a00 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
33a10 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
33a20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33a30 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
33a40 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
33a50 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
33a60 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
33a70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
33a80 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
33a90 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
33aa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
33ab0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
33ac0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
33ad0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
33ae0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
33af0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
33b00 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
33b10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
33b20 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
33b30 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
33b40 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
33b50 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73  *.** The first s
33b60 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f  ix interfaces (_
33b70 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f  blob, _double, _
33b80 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65  int, _int64, _te
33b90 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29  xt, and _text16)
33ba0 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20  .** each return 
33bb0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72  the value of a r
33bc0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20  esult column in 
33bd0 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 20  a specific data 
33be0 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74  format.  If.** t
33bf0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
33c00 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c   is not initiall
33c10 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 73 74  y in the request
33c20 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65  ed format (for e
33c30 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68  xample,.** if th
33c40 65 20 71 75 65 72 79 20 72 65 74 75 72 6e 73 20  e query returns 
33c50 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20 74  an integer but t
33c60 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
33c70 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66 61  n_text() interfa
33c80 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f  ce.** is used to
33c90 20 65 78 74 72 61 63 74 20 74 68 65 20 76 61 6c   extract the val
33ca0 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f  ue) then an auto
33cb0 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65  matic type conve
33cc0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
33cd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
33ce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
33cf0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
33d00 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
33d10 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
33d20 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
33d30 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
33d40 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
33d50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
33d60 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
33d70 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
33d80 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
33d90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
33da0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
33db0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
33dc0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
33dd0 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  L]..** The retur
33de0 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74  n value of sqlit
33df0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
33e00 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
33e10 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20  decide which.** 
33e20 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 69 78  of the first six
33e30 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c   interface shoul
33e40 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 78 74  d be used to ext
33e50 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20  ract the column 
33e60 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61  value..** The va
33e70 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
33e80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33e90 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
33ea0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a  aningful if no.*
33eb0 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65  * automatic type
33ec0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
33ed0 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74  e occurred for t
33ee0 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73  he value in ques
33ef0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72  tion.  .** After
33f00 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
33f10 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f  on, the result o
33f20 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  f calling sqlite
33f30 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
33f40 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c  ** is undefined,
33f50 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73   though harmless
33f60 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
33f70 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
33f80 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
33f90 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
33fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
33fb0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
33fc0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
33fd0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  .**.** If the re
33fe0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
33ff0 72 20 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c  r a TEXT string,
34000 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
34010 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
34020 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  .** or sqlite3_c
34030 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
34040 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20 62  interfaces can b
34050 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d  e used to determ
34060 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20  ine the size.** 
34070 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  of that BLOB or 
34080 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
34090 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
340a0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
340b0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
340c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
340d0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
340e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
340f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
34100 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
34110 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
34120 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
34130 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
34140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34150 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
34160 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
34170 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
34180 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
34190 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
341a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
341b0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
341c0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
341d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
341e0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
341f0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
34200 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
34210 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
34220 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
34230 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
34240 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
34250 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
34260 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
34270 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
34280 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
34290 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
342a0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
342b0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
342c0 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
342d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
342e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
342f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
34300 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
34310 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
34320 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
34330 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
34340 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
34350 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
34360 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
34370 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
34380 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
34390 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
343a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
343b0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
343c0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
343d0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
343e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
343f0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
34400 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
34410 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
34420 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
34430 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
34440 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
34450 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34460 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
34470 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
34480 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
34490 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
344a0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
344b0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
344c0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
344d0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
344e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
344f0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
34500 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
34510 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
34520 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
34530 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
34540 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
34550 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
34560 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
34570 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
34580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34590 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
345a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
345b0 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
345c0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
345d0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
345e0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
345f0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
34600 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
34610 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
34620 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
34630 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
34640 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
34650 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
34660 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
34670 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
34680 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
34690 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
346a0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
346b0 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
346c0 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
346d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
346e0 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20  <b>Warning:</b> 
346f0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
34700 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
34710 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
34720 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
34730 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34740 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49  alue] object.  I
34750 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65  n a multithreade
34760 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a  d environment,.*
34770 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  * an unprotected
34780 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
34790 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62  bject may only b
347a0 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69  e used safely wi
347b0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  th.** [sqlite3_b
347c0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
347d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
347e0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
347f0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
34800 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34810 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
34820 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
34830 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
34840 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
34850 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
34860 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
34870 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
34880 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
34890 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
348a0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
348b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
348c0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20  e_bytes()], the 
348d0 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20  behavior is not 
348e0 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48  threadsafe..** H
348f0 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  ence, the sqlite
34900 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
34910 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
34920 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75   normally only u
34930 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65  seful within the
34940 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34950 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74  of .** [applicat
34960 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
34970 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76  functions] or [v
34980 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20  irtual tables], 
34990 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f  not within.** to
349a0 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74  p-level applicat
349b0 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  ion code..**.** 
349c0 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  The these routin
349d0 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  es may attempt t
349e0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61  o convert the da
349f0 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65  tatype of the re
34a00 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78  sult..** ^For ex
34a10 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
34a20 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
34a30 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
34a40 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
34a50 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
34a60 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
34a70 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
34a80 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
34a90 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
34aa0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
34ab0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
34ac0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
34ad0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
34ae0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
34af0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
34b00 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
34b10 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
34b20 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
34b30 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
34b40 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
34b50 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
34b60 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
34b70 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
34b80 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
34b90 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
34ba0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
34bb0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
34bc0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
34bd0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
34be0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
34bf0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
34c00 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
34c10 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
34c20 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
34c30 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
34c40 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
34c50 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
34c60 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
34c70 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
34c80 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
34c90 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
34ca0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
34cb0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
34cc0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
34cd0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
34ce0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
34cf0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
34d00 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
34d10 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
34d20 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
34d30 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
34d40 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
34d50 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
34d60 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
34d70 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
34d80 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
34d90 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
34da0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
34db0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
34dc0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
34dd0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
34de0 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
34df0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
34e00 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
34e10 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
34e20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
34e30 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
34e40 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
34e50 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
34e60 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
34e70 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
34e80 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
34e90 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
34ea0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
34eb0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
34ec0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
34ed0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
34ee0 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
34ef0 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
34f00 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
34f10 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
34f20 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
34f30 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
34f40 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
34f50 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
34f60 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
34f70 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
34f80 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
34f90 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
34fa0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
34fb0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
34fc0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
34fd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
34fe0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
34ff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35000 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
35010 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
35020 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
35030 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
35040 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
35050 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
35060 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
35070 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
35080 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
35090 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
350a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
350b0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
350c0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
350d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
350e0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
350f0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
35100 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
35110 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
35120 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
35130 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
35140 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
35150 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
35160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35170 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
35180 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35190 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
351a0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
351b0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
351c0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
351d0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
351e0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
351f0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
35200 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
35210 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35220 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
35230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35240 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
35250 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
35260 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
35270 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
35280 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
35290 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
352a0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
352b0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
352c0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
352d0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
352e0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
352f0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
35300 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
35310 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
35320 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
35330 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
35340 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
35350 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
35360 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
35370 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
35380 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
35390 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
353a0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
353b0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
353c0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
353d0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
353e0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
353f0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
35400 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
35410 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20  e safest policy 
35420 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
35430 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
35440 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
35450 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
35460 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
35470 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35480 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
35490 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
354a0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
354b0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
354c0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
354d0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
354e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
354f0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
35500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35510 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
35520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35530 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
35540 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
35550 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
35560 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
35570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35580 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
35590 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
355a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
355b0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
355c0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
355d0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
355e0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
355f0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
35600 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
35610 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
35620 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35630 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
35640 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
35650 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
35660 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
35670 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
35680 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
35690 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
356a0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
356b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
356c0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
356d0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
356e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
356f0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
35700 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
35710 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
35720 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
35730 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
35740 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
35750 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
35760 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
35770 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
35780 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
35790 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
357a0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
357b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
357c0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
357d0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
357e0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
357f0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
35800 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
35810 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e  matically.  Do n
35820 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  ot pass the poin
35830 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
35840 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
35850 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
35860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35870 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
35880 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
35890 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
358a0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
358b0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
358c0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
358d0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
358e0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
358f0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
35900 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
35910 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
35920 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
35930 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
35940 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
35950 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
35960 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
35970 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
35980 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
35990 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
359a0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
359b0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
359c0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
359d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
359e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
359f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
35a00 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
35a10 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
35a20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
35a30 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
35a40 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
35a50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
35a60 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
35a70 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
35a80 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
35a90 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
35aa0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
35ab0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
35ac0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
35ad0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
35ae0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
35af0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
35b00 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
35b10 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
35b20 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
35b30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
35b40 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
35b50 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
35b60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
35b70 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
35b80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
35b90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35ba0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
35bb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
35bc0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
35bd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
35be0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
35bf0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
35c00 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
35c10 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
35c20 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
35c30 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
35c40 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
35c50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
35c60 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
35c70 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
35c80 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
35c90 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
35ca0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
35cb0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
35cc0 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
35cd0 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
35ce0 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
35cf0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
35d00 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
35d10 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
35d20 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
35d30 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
35d40 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
35d50 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
35d60 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
35d70 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
35d80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
35d90 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
35da0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
35db0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
35dc0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
35dd0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
35de0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
35df0 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
35e00 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
35e10 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
35e20 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
35e30 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
35e40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
35e50 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
35e60 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
35e70 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
35e80 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
35e90 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
35ea0 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
35eb0 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
35ec0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
35ed0 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
35ee0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
35ef0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
35f00 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
35f10 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
35f20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
35f30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
35f40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
35f50 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35f60 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
35f70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
35f80 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
35f90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
35fa0 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
35fb0 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
35fc0 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
35fd0 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
35fe0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
35ff0 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
36000 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
36010 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
36020 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
36030 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
36040 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
36050 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
36060 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
36070 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
36080 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
36090 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
360a0 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
360b0 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
360c0 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
360d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
360e0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
360f0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
36100 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36110 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
36120 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
36130 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ct.** METHOD: sq
36140 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
36150 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
36160 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
36170 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
36180 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
36190 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
361a0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
361b0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
361c0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
361d0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
361e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
361f0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
36200 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
36210 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
36220 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
36230 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
36240 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
36250 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
36260 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
36270 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
36280 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
36290 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
362a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
362b0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
362c0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
362d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
362e0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
362f0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
36300 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
36310 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
36320 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
36330 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
36340 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
36350 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36360 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
36370 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
36380 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
36390 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
363a0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
363b0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
363c0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
363d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
363e0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
363f0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
36400 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
36410 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
36420 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
36430 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
36440 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
36450 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
36460 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
36470 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
36480 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
36490 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
364a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
364b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
364c0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
364d0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
364e0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
364f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
36500 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
36510 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
36520 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
36530 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
36540 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
36550 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
36560 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
36570 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
36580 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
36590 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
365a0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
365b0 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
365c0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
365d0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
365e0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
365f0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
36600 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
36610 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
36620 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
36630 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
36640 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
36650 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
36660 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
36670 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
36680 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
36690 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
366a0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
366b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
366c0 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
366d0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
366e0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
366f0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
36700 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
36710 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
36720 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
36730 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
36740 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
36750 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
36760 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
36770 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
36780 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
36790 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
367a0 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
367b0 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
367c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
367d0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
367e0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
367f0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
36800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36810 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
36820 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
36830 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
36840 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
36850 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
36860 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
36870 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
36880 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
36890 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
368a0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
368b0 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
368c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
368d0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
368e0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
368f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
36900 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
36910 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36920 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
36930 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
36940 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
36950 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
36960 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
36970 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
36980 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
36990 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
369a0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
369b0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
369c0 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
369d0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
369e0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
369f0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
36a00 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
36a10 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
36a20 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
36a30 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
36a40 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
36a50 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
36a60 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
36a70 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
36a80 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
36a90 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
36aa0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
36ab0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
36ac0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
36ad0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
36ae0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
36af0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
36b00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
36b10 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
36b20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
36b30 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
36b40 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
36b50 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
36b60 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
36b70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
36b80 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
36b90 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
36ba0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
36bb0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
36bc0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
36bd0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
36be0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
36bf0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
36c00 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
36c10 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
36c20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
36c30 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
36c40 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
36c50 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
36c60 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
36c70 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
36c80 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
36c90 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
36ca0 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
36cb0 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
36cc0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
36cd0 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
36ce0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
36cf0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
36d00 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
36d10 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
36d20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
36d30 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
36d40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36d50 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
36d60 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
36d70 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
36d80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36d90 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
36da0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
36db0 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
36dc0 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
36dd0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
36de0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
36df0 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
36e00 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
36e10 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
36e20 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
36e30 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
36e40 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
36e50 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
36e60 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
36e70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
36e80 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
36e90 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
36ea0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
36eb0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
36ec0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
36ed0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
36ee0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
36ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
36f00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
36f10 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
36f20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
36f30 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
36f40 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
36f50 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
36f60 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
36f70 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
36f80 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
36f90 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
36fa0 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
36fb0 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
36fc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
36fd0 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
36fe0 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
36ff0 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
37000 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
37010 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
37020 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
37030 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
37040 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
37050 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
37060 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
37070 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
37080 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
37090 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
370a0 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
370b0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
370c0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
370d0 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
370e0 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
370f0 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
37100 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
37110 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
37120 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
37130 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
37140 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
37150 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
37160 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
37170 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
37180 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
37190 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
371a0 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
371b0 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
371c0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
371d0 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
371e0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
371f0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
37200 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
37210 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
37220 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
37230 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
37240 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
37250 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
37260 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
37270 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
37280 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
37290 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
372a0 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
372b0 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
372c0 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
372d0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
372e0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
372f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
37300 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
37310 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
37320 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
37330 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
37340 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
37350 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
37360 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
37370 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
37380 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
37390 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
373a0 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
373b0 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
373c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
373d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
373e0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
373f0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
37400 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
37410 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
37420 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
37430 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
37440 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
37450 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
37460 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
37470 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
37480 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
37490 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
374a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
374b0 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
374c0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
374d0 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
374e0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
374f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
37500 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
37510 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
37520 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
37530 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
37540 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
37550 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
37560 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
37570 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
37580 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
37590 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
375a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
375b0 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
375c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
375d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
375e0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
375f0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
37600 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
37610 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
37620 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
37630 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
37640 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
37650 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
37660 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
37670 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
37680 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
37690 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
376a0 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
376b0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
376c0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
376d0 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
376e0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
376f0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
37700 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
37710 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
37720 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
37730 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
37740 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
37750 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
37760 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
37770 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
37780 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
37790 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
377a0 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
377b0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
377c0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
377d0 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
377e0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
377f0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
37800 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
37810 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
37820 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
37830 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
37840 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
37850 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
37860 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
37870 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
37880 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
37890 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
378a0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
378b0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
378c0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
378d0 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
378e0 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
378f0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
37900 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
37910 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
37920 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37930 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
37940 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
37950 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37960 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
37970 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
37980 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
37990 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
379a0 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
379b0 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
379c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
379d0 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
379e0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
379f0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
37a00 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
37a10 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
37a20 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
37a30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37a40 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
37a50 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
37a60 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
37a70 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
37a80 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
37a90 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
37aa0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
37ab0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
37ac0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
37ad0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
37ae0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
37af0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
37b00 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
37b10 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
37b20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
37b30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
37b40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
37b50 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
37b60 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
37b70 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
37b80 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
37b90 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
37ba0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
37bb0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
37bc0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
37bd0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
37be0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
37bf0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
37c00 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
37c10 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
37c20 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
37c30 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
37c40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37c50 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
37c60 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
37c70 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
37c80 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
37c90 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
37ca0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
37cb0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
37cc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37cd0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
37ce0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
37cf0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
37d00 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
37d10 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
37d20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
37d30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37d40 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
37d50 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
37d60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37d70 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
37d80 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
37d90 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
37da0 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
37db0 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
37dc0 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
37dd0 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
37de0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
37df0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
37e00 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20  8           1   
37e10 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34   /* IMP: R-37514
37e20 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e  -35566 */.#defin
37e30 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
37e40 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20          2    /* 
37e50 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36  IMP: R-03371-376
37e60 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  37 */.#define SQ
37e70 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
37e80 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a      3    /* IMP:
37e90 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a   R-51971-34154 *
37ea0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
37eb0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
37ec0 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
37ed0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
37ee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37ef0 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
37f00 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65      /* Deprecate
37f10 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
37f20 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
37f30 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
37f40 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37f50 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
37f60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
37f70 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a  ction Flags.**.*
37f80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
37f90 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f  s may be ORed to
37fa0 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20  gether with the 
37fb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
37fc0 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78   | preferred tex
37fd0 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74  t encoding] as t
37fe0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
37ff0 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  nt.** to [sqlite
38000 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38010 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
38020 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
38030 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
38040 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
38050 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64  ion_v2()]..*/.#d
38060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
38070 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78  ERMINISTIC    0x
38080 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
38090 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
380a0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
380b0 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
380c0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
380d0 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
380e0 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
380f0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
38100 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
38110 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
38120 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
38130 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
38140 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
38150 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
38160 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
38170 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
38180 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
38190 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75  tions.  To encou
381a0 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73  rage programmers
381b0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65   to avoid.** the
381c0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
381d0 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69   will not explai
381e0 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  n what they do..
381f0 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
38200 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
38210 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
38220 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
38230 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
38240 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38250 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
38260 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
38270 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
38280 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
38290 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
382a0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
382b0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
382c0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
382d0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
382e0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
382f0 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
38300 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
38310 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
38320 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
38330 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
38340 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
38350 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
38360 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
38370 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
38380 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
38390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
383a0 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
383b0 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
383c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
383d0 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
383e0 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
383f0 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
38400 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79  **.** <b>Summary
38410 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  :</b>.** <blockq
38420 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64  uote><table bord
38430 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67  er=0 cellpadding
38440 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30  =0 cellspacing=0
38450 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  >.** <tr><td><b>
38460 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
38470 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ob</b><td>&rarr;
38480 3c 74 64 3e 42 4c 4f 42 20 76 61 6c 75 65 0a 2a  <td>BLOB value.*
38490 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
384a0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
384b0 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
384c0 74 64 3e 52 45 41 4c 20 76 61 6c 75 65 0a 2a 2a  td>REAL value.**
384d0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
384e0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 3c 2f 62  te3_value_int</b
384f0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33  ><td>&rarr;<td>3
38500 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20 76 61  2-bit INTEGER va
38510 6c 75 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  lue.** <tr><td><
38520 62 3e 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  b>sqlite3_value_
38530 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61  int64</b><td>&ra
38540 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e  rr;<td>64-bit IN
38550 54 45 47 45 52 20 76 61 6c 75 65 0a 2a 2a 20 3c  TEGER value.** <
38560 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
38570 33 5f 76 61 6c 75 65 5f 74 65 78 74 3c 2f 62 3e  3_value_text</b>
38580 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54  <td>&rarr;<td>UT
38590 46 2d 38 20 54 45 58 54 20 76 61 6c 75 65 0a 2a  F-8 TEXT value.*
385a0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
385b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
385c0 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  6</b><td>&rarr;<
385d0 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20 76  td>UTF-16 TEXT v
385e0 61 6c 75 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  alue in.** the n
385f0 61 74 69 76 65 20 62 79 74 65 6f 72 64 65 72 0a  ative byteorder.
38600 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
38610 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
38620 31 36 62 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  16be</b><td>&rar
38630 72 3b 3c 74 64 3e 55 54 46 2d 31 36 62 65 20 54  r;<td>UTF-16be T
38640 45 58 54 20 76 61 6c 75 65 0a 2a 2a 20 3c 74 72  EXT value.** <tr
38650 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
38660 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3c 2f  value_text16le</
38670 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
38680 55 54 46 2d 31 36 6c 65 20 54 45 58 54 20 76 61  UTF-16le TEXT va
38690 6c 75 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26  lue.** <tr><td>&
386a0 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c  nbsp;<td>&nbsp;<
386b0 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72  td>&nbsp;.** <tr
386c0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
386d0 76 61 6c 75 65 5f 62 79 74 65 73 3c 2f 62 3e 3c  value_bytes</b><
386e0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a  td>&rarr;