/ Hex Artifact Content
Login

Artifact 17faafcb9f410b8140c766c5faf8334da37079ddf4c5054da201071a02190f54:


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 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [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 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [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 42 55 53 59 5f 44 45 41 44  SQLITE_BUSY_DEAD
57f0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
5800: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
5810: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5820: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5830: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
5840: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5850: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5870: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
5880: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5890: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
58a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
58b0: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
58c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
58d0: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
58e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
58f0: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
5900: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5910: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5930: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5940: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5950: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5960: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5970: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5980: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5990: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
59a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
59b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
59c0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
59d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
59e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59f0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5a00: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
5a10: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5a20: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5a30: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5a40: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
5a50: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5a60: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5a70: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5a80: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5a90: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5aa0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5ab0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ac0: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
5ad0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ae0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
5af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5b00: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
5b10: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
5b20: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b40: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5b50: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5b60: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5b70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5b90: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5ba0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5bb0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5bc0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5bd0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5be0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bf0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5c10: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5c20: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5c30: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c50: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5c60: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5c70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5c80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5c90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5ca0: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5cb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5cc0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5cd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ce0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5cf0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5d00: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5d10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5d20: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5d30: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d40: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d60: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5d70: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5d80: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
5d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5da0: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
5db0: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
5dc0: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5de0: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
5df0: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
5e00: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
5e10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5e20: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
5e30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5e40: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
5e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e60: 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54  K_LOAD_PERMANENT
5e70: 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f  LY     (SQLITE_O
5e80: 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  K | (1<<8))../*.
5e90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5ea0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5eb0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5ec0: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5ed0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5ee0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5ef0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5f00: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5f10: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5f20: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5f30: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5f40: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5f50: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5f60: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5f70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5f80: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5f90: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5fa0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5fd0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5fe0: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5ff0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6000: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6010: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
6020: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
6030: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
6040: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6050: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6060: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
6070: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
6080: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
6090: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
60b0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
60c0: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
60d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
60f0: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
6100: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
6110: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6120: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
6130: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6140: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
6150: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6160: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6170: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6180: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6190: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
61a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
61b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
61d0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
61e0: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
61f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6210: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6220: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
6230: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6240: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
6250: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
6260: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
6270: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6280: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6290: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
62a0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
62b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
62c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
62d0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
62e0: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
62f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6300: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6310: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
6320: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
6330: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
6350: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
6360: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
6370: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6380: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6390: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
63a0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
63b0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
63c0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
63d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
63e0: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
63f0: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6400: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6410: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6420: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
6430: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
6440: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
6450: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6460: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6470: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6480: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6490: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
64a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
64b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
64c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
64d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
64e0: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
64f0: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6500: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6510: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6520: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6530: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6540: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
6550: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
6560: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6570: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6580: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6590: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
65a0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
65b0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
65c0: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
65d0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
65e0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
65f0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6600: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6610: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6620: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6630: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6640: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6650: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
6660: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6670: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6680: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6690: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
66a0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
66b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
66c0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
66d0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
66e0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
66f0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6700: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6710: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6720: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6730: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6740: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6750: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
6760: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6770: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6780: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6790: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
67a0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
67b0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
67c0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
67d0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
67e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
67f0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6800: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6810: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6820: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6830: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6840: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6850: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
6860: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6870: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6880: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6890: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
68a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
68b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
68c0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
68d0: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
68e0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
68f0: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6900: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6910: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6920: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6930: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6940: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6950: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
6960: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6970: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6980: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6990: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
69a0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
69b0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
69c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
69d0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
69e0: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
69f0: 69 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69  icates that a fi
6a00: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6a10: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6a20: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6a30: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6a40: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6a50: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6a60: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6a70: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
6a80: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
6a90: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
6aa0: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
6ab0: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6af0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6b10: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6b20: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6b60: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b90: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6bb0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
6bc0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6bf0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c00: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6c20: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6c30: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6c40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c50: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6c60: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6c70: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
6c80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6c90: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
6ca0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
6cb0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6cc0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
6cd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6ce0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6cf0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6d00: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6d10: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6d20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6d30: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6d40: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d60: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6d70: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6d80: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
6d90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6da0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
6db0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
6dc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6dd0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6de0: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6df0: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6e00: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6e10: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6e20: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6e30: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6e40: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6e50: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
6e60: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6e70: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6e80: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6e90: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6ea0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6ec0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6ed0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6ee0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6ef0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6f00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6f10: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6f20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6f30: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6f40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6f50: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
6f60: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6f70: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6f80: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6f90: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6fb0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6fc0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6fd0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6fe0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6ff0: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
7000: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
7010: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
7020: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
7030: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
7040: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
7050: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
7060: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
7070: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
7080: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
7090: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
70a0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
70b0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
70c0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
70d0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
70e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
70f0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
7100: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
7110: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
7120: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
7130: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
7140: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7150: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
7160: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
7170: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
7180: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
7190: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
71a0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
71b0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
71c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
71d0: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
71e0: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
71f0: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
7200: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
7210: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
7220: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
7230: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
7240: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
7250: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
7260: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
7270: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
7280: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
7290: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
72a0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
72b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
72c0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
72d0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
72e0: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
72f0: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
7300: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
7310: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
7320: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
7330: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
7340: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
7350: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
7360: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
7370: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
7380: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7390: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
73a0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
73b0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
73c0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
73d0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
73e0: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
73f0: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
7400: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
7410: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
7420: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
7430: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
7440: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
7450: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
7460: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7470: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
7480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7490: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
74a0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
74b0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
74c0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
74d0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
74e0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
74f0: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
7500: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
7510: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7520: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
7530: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
7540: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
7550: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
7560: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
7570: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
7580: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
7590: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
75a0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
75b0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
75c0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
75d0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
75e0: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
75f0: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
7600: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
7610: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
7620: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7630: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
7640: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
7650: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
7660: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7670: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
7680: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7690: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
76a0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
76b0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
76c0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
76d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
76e0: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
76f0: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7700: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7710: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7720: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
7730: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
7740: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
7750: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
7760: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7770: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
7780: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
7790: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
77a0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
77b0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
77c0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
77d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
77e0: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
77f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7800: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7810: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
7820: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7830: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
7840: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
7850: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
7860: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
7870: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
7880: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
7890: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
78a0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
78b0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
78c0: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
78d0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
78e0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
78f0: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7900: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7910: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
7920: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
7930: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
7940: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
7950: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7960: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
7970: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
7980: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
7990: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
79a0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
79b0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
79c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
79d0: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
79e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
79f0: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7a00: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7a10: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
7a20: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
7a30: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
7a40: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
7a50: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
7a60: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
7a70: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
7a80: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
7a90: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
7aa0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
7ab0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
7ac0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
7ad0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7ae0: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7af0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7b00: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7b10: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
7b20: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
7b30: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
7b40: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
7b50: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
7b60: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
7b70: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
7b80: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
7b90: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
7ba0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
7bb0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7bc0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
7bd0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7be0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7bf0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7c00: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7c10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7c20: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
7c30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7c40: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
7c50: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
7c60: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
7c70: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
7c80: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
7c90: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
7ca0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
7cb0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
7cc0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
7cd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7ce0: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7cf0: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7d00: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7d10: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7d20: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7d30: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7d40: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7d50: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
7d60: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7d70: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7d80: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7d90: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7da0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7db0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7dc0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7dd0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7de0: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7df0: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7e00: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7e10: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7e20: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7e30: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7e40: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7e50: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
7e60: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7e70: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7e80: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7e90: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7ea0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7eb0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7ec0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7ed0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7ee0: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7ef0: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7f00: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7f10: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7f20: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7f30: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7f40: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7f50: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
7f60: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7f70: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7f80: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7f90: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7fa0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7fb0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7fc0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7fd0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7fe0: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7ff0: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
8000: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
8010: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
8020: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
8030: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
8040: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
8050: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
8060: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
8070: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
8080: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
8090: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
80a0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
80b0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
80c0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
80d0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
80e0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
80f0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
8100: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
8110: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
8120: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
8130: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
8140: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
8150: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
8160: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
8170: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
8180: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
8190: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
81a0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
81b0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
81c0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
81d0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
81e0: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
81f0: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
8200: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
8210: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
8220: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
8230: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
8240: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
8250: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
8260: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
8270: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
8280: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
8290: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
82a0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
82b0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
82c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
82d0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <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 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
8300: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8310: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8320: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8330: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8340: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8350: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <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 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
8380: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8390: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
83a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
83b0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
83c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
83d0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
83e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
83f0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
8400: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8410: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8420: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8430: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
8440: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a  BLE_WHEN_OPEN].*
8450: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8460: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
8470: 56 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69  VERWRITE].** <li
8480: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8490: 49 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f  IMMUTABLE].** </
84a0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
84b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
84c0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
84d0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
84e0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
84f0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8500: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8510: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
8520: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
8530: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
8540: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
8550: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8560: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8570: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8580: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8590: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
85a0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
85b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
85c0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
85d0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
85e0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
85f0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
8600: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
8610: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
8620: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
8630: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
8640: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
8650: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8660: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8670: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8680: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8690: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
86a0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
86b0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
86c0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
86d0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
86e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
86f0: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
8700: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
8710: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
8720: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
8730: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
8740: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
8750: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
8760: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
8770: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8780: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
8790: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
87a0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
87b0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
87c0: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
87d0: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
87e0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
87f0: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
8800: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
8810: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
8820: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
8830: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
8840: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
8850: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
8860: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
8870: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8880: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
8890: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
88a0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
88b0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
88c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
88d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
88e0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
88f0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8900: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8910: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
8920: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8930: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
8940: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
8950: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
8960: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
8970: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
8980: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8990: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
89a0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
89b0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
89c0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
89d0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
89e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
89f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
8a00: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
8a10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8a20: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
8a30: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
8a40: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a50: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
8a60: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
8a70: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
8a80: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8a90: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
8aa0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
8ab0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
8ac0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8ad0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8ae0: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
8af0: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
8b00: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
8b10: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
8b20: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
8b30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
8b40: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8b50: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
8b60: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
8b70: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
8b80: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
8b90: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8ba0: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
8bb0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
8bc0: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
8bd0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8be0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8bf0: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
8c00: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
8c10: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8c20: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
8c30: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
8c40: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
8c50: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8c60: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8c70: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
8c80: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
8c90: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8ca0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
8cb0: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
8cc0: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
8cd0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
8ce0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
8cf0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8d00: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
8d10: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
8d20: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
8d30: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8d40: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
8d50: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
8d60: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8d70: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8d80: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8d90: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8da0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8db0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8dc0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
8dd0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8de0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
8df0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75  erface..**.** <u
8e00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
8e10: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8e20: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  TE]].** The [SQL
8e30: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
8e40: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
8e50: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
8e60: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
8e70: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
8e80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8e90: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
8ea0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
8eb0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
8ec0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
8ed0: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
8ee0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
8ef0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
8f00: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
8f10: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
8f20: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
8f30: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
8f40: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
8f50: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
8f60: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
8f70: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
8f80: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
8f90: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69  ng testing and i
8fa0: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
8fb0: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
8fc0: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65  _TEST.** compile
8fd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
8fe0: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  used..**.** <li>
8ff0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9000: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
9010: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9020: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
9030: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
9040: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
9050: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
9060: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
9070: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9080: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
9090: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
90a0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
90b0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
90c0: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
90d0: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
90e0: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
90f0: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
9100: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
9110: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
9120: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
9130: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
9140: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
9150: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
9160: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
9170: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9180: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
9190: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
91a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
91b0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
91c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
91d0: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
91e0: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
91f0: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
9200: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
9210: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
9220: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
9230: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
9240: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
9250: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
9260: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
9270: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9280: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
9290: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
92a0: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
92b0: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
92c0: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
92d0: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
92e0: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
92f0: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
9300: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
9310: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
9320: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
9330: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
9340: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
9350: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
9360: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
9370: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
9380: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
9390: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
93a0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
93b0: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
93c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
93d0: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
93e0: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
93f0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
9400: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9410: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
9420: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
9430: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
9440: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9450: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
9460: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9470: 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  L_POINTER]..**.*
9480: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9490: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
94a0: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
94b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
94c0: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  NAL_POINTER] opc
94d0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
94e0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
94f0: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
9500: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9510: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9520: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  the journal file
9530: 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20   (either.** the 
9540: 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61  [rollback journa
9550: 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65  l] or the [write
9560: 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72  -ahead log]) for
9570: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
9580: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
9590: 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20  tion.  See also 
95a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
95b0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a  LE_POINTER]..**.
95c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
95d0: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
95e0: 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65  ED]].** No longe
95f0: 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  r in use..**.** 
9600: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9610: 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65  TL_SYNC]].** The
9620: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
9630: 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  YNC] opcode is g
9640: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9650: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e  lly by SQLite an
9660: 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65  d.** sent to the
9670: 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79   VFS immediately
9680: 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e   before the xSyn
9690: 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  c method is invo
96a0: 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61  ked on a.** data
96b0: 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69  base file descri
96c0: 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65  ptor. Or, if the
96d0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
96e0: 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a   not invoked .**
96f0: 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65   because the use
9700: 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64  r has configured
9710: 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a   SQLite with .**
9720: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
9730: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
9740: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
9750: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20  t is invoked in 
9760: 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65  place .** of the
9770: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49   xSync method. I
9780: 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68  n most cases, th
9790: 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
97a0: 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a  nt passed with.*
97b0: 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  * this file-cont
97c0: 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77  rol is NULL. How
97d0: 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74  ever, if the dat
97e0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65  abase file is be
97f0: 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73  ing synced.** as
9800: 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69   part of a multi
9810: 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74  -database commit
9820: 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  , the argument p
9830: 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74  oints to a nul-t
9840: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
9850: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
9860: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  he transactions 
9870: 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66  master-journal f
9880: 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20  ile name. VFSes 
9890: 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20  that .** do not 
98a0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
98b0: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
98c0: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
98d0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
98e0: 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  s .** should not
98f0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
9900: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
9910: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
9920: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
9930: 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20  .** disrupt the 
9940: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
9950: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9960: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
9970: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9980: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9990: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
99a0: 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  O]].** The [SQLI
99b0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
99c0: 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65  PHASETWO] opcode
99d0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
99e0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
99f0: 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74  te.** and sent t
9a00: 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20  o the VFS after 
9a10: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61  a transaction ha
9a20: 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  s been committed
9a30: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
9a40: 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64  but before the d
9a50: 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63  atabase is unloc
9a60: 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20  ked. VFSes that 
9a70: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
9a80: 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c   signal.** shoul
9a90: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9aa0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9ab0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
9ac0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b  ld not call.** [
9ad0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9ae0: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9af0: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9b00: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
9b10: 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69   the .** operati
9b20: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
9b30: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
9b40: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
9b50: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
9b60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9b70: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e  _AV_RETRY]].** ^
9b80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9b90: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
9ba0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9bb0: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
9bc0: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
9bd0: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
9be0: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
9bf0: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
9c00: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
9c10: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
9c20: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
9c30: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
9c40: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
9c50: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
9c60: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
9c70: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
9c80: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
9c90: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
9ca0: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
9cb0: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
9cc0: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
9cd0: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
9ce0: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
9cf0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
9d00: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
9d10: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
9d20: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
9d30: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
9d40: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
9d50: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
9d60: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
9d70: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
9d80: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
9d90: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
9da0: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
9db0: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
9dc0: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
9dd0: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
9de0: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
9df0: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
9e00: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
9e10: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
9e20: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
9e30: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
9e40: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
9e50: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
9e60: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
9e70: 74 65 67 65 72 20 69 73 20 74 68 65 20 6e 65 77  teger is the new
9e80: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
9e90: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
9ea0: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
9eb0: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
9ec0: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
9ed0: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
9ee0: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
9ef0: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
9f00: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
9f10: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
9f20: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
9f30: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
9f40: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
9f50: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
9f60: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
9f70: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
9f80: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
9f90: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
9fa0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
9fb0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
9fc0: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
9fd0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9fe0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
9ff0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a000: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
a010: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
a020: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68   [WAL | Write Ah
a030: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
a040: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
a050: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
a060: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
a070: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
a080: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
a090: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
a0a0: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
a0b0: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
a0c0: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
a0d0: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
a0e0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
a0f0: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
a100: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a110: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
a120: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
a130: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
a140: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
a150: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
a160: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
a170: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
a180: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
a190: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
a1a0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
a1b0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
a1c0: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
a1d0: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
a1e0: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
a1f0: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
a200: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a210: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
a220: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
a230: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
a240: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
a250: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a260: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a270: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a280: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a290: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a2a0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a2b0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a2c0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a2d0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a2e0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a2f0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
a300: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
a310: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a320: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a330: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a340: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
a350: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
a360: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a370: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a380: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a390: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a3a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a3b0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a3c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a3d0: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a3e0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a3f0: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
a400: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
a410: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
a420: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
a430: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
a440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
a450: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a460: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
a470: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
a480: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
a490: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a4a0: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a4b0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a4c0: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a4d0: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a4e0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a4f0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a500: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a510: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
a520: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
a530: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
a540: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
a550: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a560: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a570: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a580: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
a590: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
a5a0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a5b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a5c0: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a5d0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a5e0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
a5f0: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
a600: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
a610: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
a620: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
a630: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
a640: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
a650: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
a660: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
a670: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
a680: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
a690: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
a6a0: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
a6b0: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
a6c0: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
a6d0: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
a6e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a6f0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
a700: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a710: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
a720: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
a730: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
a740: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
a750: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
a760: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
a770: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
a780: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
a790: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
a7a0: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
a7b0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
a7c0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
a7d0: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
a7e0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
a7f0: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
a800: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
a810: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
a820: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
a830: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
a840: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a850: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
a860: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
a870: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
a880: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
a890: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
a8a0: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
a8b0: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
a8c0: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
a8d0: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
a8e0: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
a8f0: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
a900: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
a910: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
a920: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
a930: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
a940: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
a950: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
a960: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
a970: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
a980: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
a990: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
a9a0: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
a9b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a9c0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
a9d0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a9e0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
a9f0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e  NTER] opcode fin
aa00: 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ds a pointer to 
aa10: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a  the top-level.**
aa20: 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74   [VFSes] current
aa30: 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68  ly in use.  ^(Th
aa40: 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a  e argument X in.
aa50: 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  ** sqlite3_file_
aa60: 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54  control(db,SQLIT
aa70: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
aa80: 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a  TER,X) must be.*
aa90: 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69  * of type "[sqli
aaa0: 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54  te3_vfs] **".  T
aab0: 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c  his opcodes will
aac0: 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20   set *X.** to a 
aad0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
aae0: 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a  op-level VFS.)^.
aaf0: 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61  ** ^When there a
ab00: 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20  re multiple VFS 
ab10: 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61  shims in the sta
ab20: 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ck, this opcode 
ab30: 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70  finds the.** upp
ab40: 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c  er-most shim onl
ab50: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
ab60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ab70: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
ab80: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
ab90: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
aba0: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
abb0: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
abc0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
abd0: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
abe0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
abf0: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
ac00: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
ac10: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
ac20: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
ac30: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
ac40: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
ac50: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
ac60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ac70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
ac80: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
ac90: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
aca0: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
acb0: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
acc0: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
acd0: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
ace0: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
acf0: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
ad00: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
ad10: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
ad20: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
ad30: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
ad40: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
ad50: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
ad60: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
ad70: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
ad80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
ad90: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
ada0: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
adb0: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
adc0: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
add0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
ade0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
adf0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
ae00: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
ae10: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
ae20: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
ae30: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
ae40: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
ae50: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
ae60: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
ae70: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
ae80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ae90: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
aea0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
aeb0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
aec0: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
aed0: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
aee0: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
aef0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
af00: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
af10: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
af20: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
af30: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
af40: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
af50: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
af60: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
af70: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
af80: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
af90: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
afa0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
afb0: 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20  f result string 
afc0: 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74  is NULL, or that
afd0: 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a   returns a copy.
afe0: 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
aff0: 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73   string if the s
b000: 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c  tring is non-NUL
b010: 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  L..** ^If the [S
b020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b030: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b040: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
b050: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
b060: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
b070: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
b080: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
b090: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
b0a0: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
b0b0: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
b0c0: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
b0d0: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
b0e0: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
b0f0: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
b100: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
b110: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
b120: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
b130: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
b140: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
b150: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
b160: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
b170: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
b180: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
b190: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
b1a0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
b1b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b1c0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b1d0: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  LER]].** ^The [S
b1e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b1f0: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65  HANDLER].** file
b200: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
b210: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
b220: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
b230: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
b240: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
b250: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
b260: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
b270: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
b280: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
b290: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
b2a0: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
b2b0: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
b2c0: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
b2d0: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
b2e0: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
b2f0: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
b300: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
b310: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
b320: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
b330: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
b340: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
b350: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
b360: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
b370: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
b380: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
b390: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
b3a0: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
b3b0: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
b3c0: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
b3d0: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
b3e0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
b3f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
b400: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
b410: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
b420: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
b430: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
b440: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
b450: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
b460: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
b470: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b480: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b490: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
b4a0: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
b4b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b4c0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20  L_TEMPFILENAME] 
b4d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
b4e0: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67  to have SQLite g
b4f0: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d  enerate a.** tem
b500: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20  porary filename 
b510: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
b520: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73  lgorithm that is
b530: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e   followed to gen
b540: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  erate.** tempora
b550: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72  ry filenames for
b560: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64   TEMP tables and
b570: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20   other internal 
b580: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72  uses.  The.** ar
b590: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
b5a0: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20   a char** which 
b5b0: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77  will be filled w
b5c0: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ith the filename
b5d0: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  .** written into
b5e0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
b5f0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
b600: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63  alloc()].  The c
b610: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20  aller should.** 
b620: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
b630: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72  free()] on the r
b640: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61  esult to avoid a
b650: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a   memory leak..**
b660: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b670: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b680: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b690: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b6a0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b6b0: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79  is used to query
b6c0: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d   or set the.** m
b6d0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b6e0: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c   bytes that will
b6f0: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d   be used for mem
b700: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
b710: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b720: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
b730: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20  a value of type 
b740: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68  sqlite3_int64 th
b750: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69  at.** is an advi
b760: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  sory maximum num
b770: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
b780: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f  the file to memo
b790: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20  ry map.  The.** 
b7a0: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77  pointer is overw
b7b0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
b7c0: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20  old value.  The 
b7d0: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61  limit is not cha
b7e0: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76  nged if.** the v
b7f0: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  alue originally 
b800: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65  pointed to is ne
b810: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74  gative, and so t
b820: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74  he current limit
b830: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72   .** can be quer
b840: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  ied by passing i
b850: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  n a pointer to a
b860: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
b870: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d  .  This.** file-
b880: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b890: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d  internally to im
b8a0: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20  plement [PRAGMA 
b8b0: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a  mmap_size]..**.*
b8c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b8d0: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20  CNTL_TRACE]].** 
b8e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b8f0: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f  L_TRACE] file co
b900: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61  ntrol provides a
b910: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74  dvisory informat
b920: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46  ion.** to the VF
b930: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65  S about what the
b940: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f   higher layers o
b950: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61  f the SQLite sta
b960: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a  ck are doing..**
b970: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
b980: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f  ol is used by so
b990: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20  me VFS activity 
b9a0: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e  tracing [shims].
b9b0: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
b9c0: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
b9d0: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48  nated string.  H
b9e0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20  igher layers in 
b9f0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74  the.** SQLite st
ba00: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65  ack may generate
ba10: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68   instances of th
ba20: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
ba30: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  if.** the [SQLIT
ba40: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43  E_USE_FCNTL_TRAC
ba50: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
ba60: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
ba70: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
ba80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
ba90: 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b  MOVED]].** The [
baa0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
bab0: 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e  _MOVED] file con
bac0: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
bad0: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
bae0: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
baf0: 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69  an integer and i
bb00: 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65  t writes a boole
bb10: 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  an into that int
bb20: 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a  eger depending.*
bb30: 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20  * on whether or 
bb40: 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73  not the file has
bb50: 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d   been renamed, m
bb60: 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  oved, or deleted
bb70: 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73   since it.** was
bb80: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a   first opened..*
bb90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bba0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
bbb0: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
bbc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bbd0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
bbe0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
bbf0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
bc00: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
bc10: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
bc20: 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  dle associated w
bc30: 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c  ith a file handl
bc40: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a  e.  This file.**
bc50: 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72   control interpr
bc60: 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74  ets its argument
bc70: 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   as a pointer to
bc80: 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68   a native file h
bc90: 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69  andle and.** wri
bca0: 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e  tes the resultin
bcb0: 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a  g value there..*
bcc0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bcd0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
bce0: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
bcf0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bd00: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bd10: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
bd20: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
bd30: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
bd40: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
bd50: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
bd60: 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20  o swap the file 
bd70: 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20  handle with the 
bd80: 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  one.** pointed t
bd90: 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72  o by the pArg ar
bda0: 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61  gument.  This ca
bdb0: 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64  pability is used
bdc0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a   during testing.
bdd0: 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ** and only need
bde0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
bdf0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
be00: 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ST is defined..*
be10: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
be20: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
be30: 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  K]].** The [SQLI
be40: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
be50: 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20  CK] is a signal 
be60: 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72  to the VFS layer
be70: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a   that it might.*
be80: 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75  * be advantageou
be90: 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68  s to block on th
bea0: 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20  e next WAL lock 
beb0: 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e  if the lock is n
bec0: 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ot immediately.*
bed0: 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68  * available.  Th
bee0: 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20  e WAL subsystem 
bef0: 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e  issues this sign
bf00: 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a  al during rare.*
bf10: 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  * circumstances 
bf20: 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20  in order to fix 
bf30: 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70  a problem with p
bf40: 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f  riority inversio
bf50: 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  n..** Applicatio
bf60: 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f  ns should <em>no
bf70: 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20  t</em> use this 
bf80: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a  file-control..**
bf90: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bfa0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a  _FCNTL_ZIPVFS]].
bfb0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bfc0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63  CNTL_ZIPVFS] opc
bfd0: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
bfe0: 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c  ed by zipvfs onl
bff0: 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  y. All other.** 
c000: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c010: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c020: 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  D for this opcod
c030: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
c040: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c050: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c060: 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f  _FCNTL_RBU] opco
c070: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
c080: 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c  d by the special
c090: 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20   VFS used by.** 
c0a0: 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f  the RBU extensio
c0b0: 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68  n only.  All oth
c0c0: 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  er VFS should re
c0d0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
c0e0: 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73  OUND for.** this
c0f0: 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f   opcode.  .** </
c100: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
c110: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
c120: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
c130: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
c140: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
c150: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c160: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
c170: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
c180: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c190: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
c1a0: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
c1b0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
c1c0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
c1d0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
c1e0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
c1f0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
c200: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
c210: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
c220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c230: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
c240: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
c250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c260: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
c270: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
c280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c290: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
c2a0: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
c2b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c2c0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
c2d0: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
c2e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c2f0: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
c300: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
c310: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c320: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
c330: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
c340: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c350: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
c360: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
c370: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
c380: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
c390: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
c3a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
c3b0: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
c3c0: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
c3d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
c3e0: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
c3f0: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
c400: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
c410: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
c420: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51     18.#define SQ
c430: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
c440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c450: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    19.#define SQL
c460: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
c470: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  VED             
c480: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   20.#define SQLI
c490: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20  TE_FCNTL_SYNC   
c4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c4b0: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  21.#define SQLIT
c4c0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
c4d0: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32  HASETWO        2
c4e0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
c4f0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
c500: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33  _HANDLE       23
c510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c520: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20  FCNTL_WAL_BLOCK 
c530: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a               24.
c540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c550: 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20  CNTL_ZIPVFS     
c560: 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23              25.#
c570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c580: 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20  NTL_RBU         
c590: 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64             26.#d
c5a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c5b0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20  TL_VFS_POINTER  
c5c0: 20 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65            27.#de
c5d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c5e0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
c5f0: 52 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66  R        28.#def
c600: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c610: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
c620: 45 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69  E       29.#defi
c630: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c640: 50 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20  PDB             
c650: 20 20 20 20 20 20 20 33 30 0a 23 64 65 66 69 6e         30.#defin
c660: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
c670: 49 4c 45 49 44 20 20 20 20 20 20 20 20 20 20 20  ILEID           
c680: 20 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e 65        31.#define
c690: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c6a0: 52 56 45 52 5f 4d 4f 44 45 20 20 20 20 20 20 20  RVER_MODE       
c6b0: 20 20 20 20 20 33 32 0a 0a 2f 2a 20 64 65 70 72       32../* depr
c6c0: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
c6d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
c6e0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c6f0: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c700: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
c710: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
c720: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
c730: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
c740: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
c750: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
c760: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
c770: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
c780: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
c790: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
c7a0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
c7b0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
c7c0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
c7d0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
c7e0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
c7f0: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
c800: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
c810: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
c820: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
c830: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
c840: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
c850: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
c860: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
c870: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
c880: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
c890: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
c8a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
c8b0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
c8c0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
c8d0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
c8e0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
c8f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c900: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
c910: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
c920: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c930: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
c940: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
c950: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
c960: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
c970: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
c980: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
c990: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
c9a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
c9b0: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
c9c0: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
c9d0: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
c9e0: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
c9f0: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
ca00: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
ca10: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
ca20: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
ca30: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
ca40: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
ca50: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
ca60: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
ca70: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
ca80: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
ca90: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
caa0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
cab0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
cac0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
cad0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
cae0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
caf0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
cb00: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
cb10: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
cb20: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
cb30: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
cb40: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
cb50: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
cb60: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
cb70: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
cb80: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
cb90: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
cba0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
cbb0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
cbc0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
cbd0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
cbe0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
cbf0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
cc00: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
cc10: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
cc20: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
cc30: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
cc40: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
cc50: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
cc60: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
cc70: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
cc80: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
cc90: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
cca0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
ccb0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
ccc0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
ccd0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
cce0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
ccf0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
cd00: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
cd10: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
cd20: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
cd30: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
cd40: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
cd50: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
cd60: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
cd70: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
cd80: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
cd90: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
cda0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
cdb0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
cdc0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
cdd0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
cde0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
cdf0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
ce00: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
ce10: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
ce20: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
ce30: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
ce40: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
ce50: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
ce60: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
ce70: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
ce80: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
ce90: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
cea0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
ceb0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
cec0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
ced0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
cee0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
cef0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
cf00: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
cf10: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
cf20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
cf30: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
cf40: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
cf50: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
cf60: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
cf70: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
cf80: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
cf90: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
cfa0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
cfb0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
cfc0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
cfd0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
cfe0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
cff0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
d000: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
d010: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
d020: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
d030: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
d040: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
d050: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
d060: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
d070: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
d080: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
d090: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
d0a0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
d0b0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
d0c0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
d0d0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
d0e0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
d0f0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
d100: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d110: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
d120: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
d130: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
d140: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
d150: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
d160: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
d170: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
d180: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
d190: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
d1a0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
d1b0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
d1c0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
d1d0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
d1e0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
d1f0: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
d200: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
d210: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
d220: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
d230: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
d240: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
d250: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
d260: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
d270: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
d280: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
d290: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
d2a0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
d2b0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
d2c0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
d2d0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
d2e0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
d2f0: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
d300: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
d310: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
d320: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
d330: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
d340: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d350: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
d360: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
d370: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
d380: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
d390: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
d3a0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
d3b0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
d3c0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
d3d0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
d3e0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
d3f0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
d400: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
d410: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
d420: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d430: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
d440: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
d450: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
d460: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
d470: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
d480: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
d490: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
d4a0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
d4b0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
d4c0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
d4d0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
d4e0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
d4f0: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
d500: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
d510: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
d520: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
d530: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
d540: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
d550: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
d560: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
d570: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
d580: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
d590: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
d5a0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
d5b0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
d5c0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
d5d0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
d5e0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
d5f0: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
d600: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
d610: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
d620: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
d630: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
d640: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
d650: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d660: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
d670: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d680: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
d690: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
d6a0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
d6b0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
d6c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
d6d0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
d6e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d6f0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
d700: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d710: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
d720: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d730: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
d740: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
d750: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
d760: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
d770: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
d780: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
d790: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
d7a0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
d7b0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
d7c0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
d7d0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
d7e0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
d7f0: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
d800: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
d810: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
d820: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
d830: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
d840: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
d850: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
d860: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
d870: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
d880: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
d890: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
d8a0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
d8b0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
d8c0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
d8d0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
d8e0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
d8f0: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
d900: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
d910: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
d920: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
d930: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
d940: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
d950: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
d960: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
d970: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
d980: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
d990: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
d9a0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
d9b0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
d9c0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d9d0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
d9e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
d9f0: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
da00: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
da10: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
da20: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
da30: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
da40: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
da50: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
da60: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
da70: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
da80: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
da90: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
daa0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
dab0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
dac0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
dad0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
dae0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
daf0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
db00: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
db10: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
db20: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
db30: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
db40: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
db50: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
db60: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
db70: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
db80: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
db90: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
dba0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
dbb0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
dbc0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
dbd0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
dbe0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
dbf0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
dc00: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
dc10: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
dc20: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
dc30: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
dc40: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
dc50: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
dc60: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
dc70: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
dc80: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
dc90: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
dca0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
dcb0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
dcc0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
dcd0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
dce0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
dcf0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
dd00: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
dd10: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
dd20: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
dd30: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
dd40: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
dd50: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
dd60: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
dd70: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
dd80: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
dd90: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
dda0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
ddb0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
ddc0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
ddd0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
dde0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
ddf0: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
de00: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
de10: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
de20: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
de30: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
de40: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
de50: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
de60: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
de70: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
de80: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
de90: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
dea0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
deb0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
dec0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
ded0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
dee0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
def0: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
df00: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
df10: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
df20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
df30: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
df40: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
df50: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
df60: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
df70: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
df80: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
df90: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
dfa0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
dfb0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
dfc0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
dfd0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
dfe0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
dff0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
e000: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
e010: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
e020: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
e030: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
e040: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
e050: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
e060: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
e070: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
e080: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
e090: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
e0a0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
e0b0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e0c0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
e0d0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
e0e0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
e0f0: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
e100: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
e110: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
e120: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
e130: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
e140: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
e150: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
e160: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
e170: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
e180: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
e190: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
e1a0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
e1b0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
e1c0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
e1d0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
e1e0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
e1f0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
e200: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
e210: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
e220: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
e230: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
e240: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
e250: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
e260: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
e270: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
e280: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
e290: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
e2a0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
e2b0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
e2c0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
e2d0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
e2e0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
e2f0: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
e300: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
e310: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
e320: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
e330: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
e340: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
e350: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
e360: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
e370: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
e380: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
e390: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
e3a0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
e3b0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
e3c0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
e3d0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
e3e0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
e3f0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
e400: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
e410: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
e420: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
e430: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
e440: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
e450: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
e460: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
e470: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
e480: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
e490: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
e4a0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
e4b0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
e4c0: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
e4d0: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
e4e0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
e4f0: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
e500: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
e510: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
e520: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
e530: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
e540: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
e550: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
e560: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
e570: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
e580: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
e590: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
e5a0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
e5b0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
e5c0: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
e5d0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
e5e0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
e5f0: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
e600: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
e610: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
e620: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
e630: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
e640: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
e650: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
e660: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
e670: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
e680: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
e690: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
e6a0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
e6b0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
e6c0: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
e6d0: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
e6e0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
e6f0: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
e700: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
e710: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
e720: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
e730: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
e740: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
e750: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
e760: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
e770: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
e780: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
e790: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
e7a0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
e7b0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
e7c0: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
e7d0: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
e7e0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
e7f0: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
e800: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
e810: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
e820: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
e830: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
e840: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
e850: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
e860: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
e870: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
e880: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
e890: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
e8a0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
e8b0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
e8c0: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
e8d0: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
e8e0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
e8f0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
e900: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
e910: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
e920: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
e930: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
e940: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
e950: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
e960: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
e970: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
e980: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
e990: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
e9a0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
e9b0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
e9c0: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
e9d0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
e9e0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
e9f0: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
ea00: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
ea10: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
ea20: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
ea30: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
ea40: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
ea50: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
ea60: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
ea70: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
ea80: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
ea90: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
eaa0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
eab0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
eac0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
ead0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
eae0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
eaf0: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
eb00: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
eb10: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
eb20: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
eb30: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
eb40: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
eb50: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
eb60: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
eb70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
eb80: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
eb90: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
eba0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
ebb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
ebc0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
ebd0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ebe0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
ebf0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
ec00: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
ec10: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
ec20: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ec30: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
ec40: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
ec50: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
ec60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ec70: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
ec80: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
ec90: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
eca0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
ecb0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
ecc0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
ecd0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
ece0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
ecf0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
ed00: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
ed10: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
ed20: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
ed30: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
ed40: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
ed50: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
ed60: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
ed70: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
ed80: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
ed90: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
eda0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
edb0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
edc0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
edd0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
ede0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
edf0: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
ee00: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ee10: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
ee20: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
ee30: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
ee40: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
ee50: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
ee60: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
ee70: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
ee80: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
ee90: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
eea0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
eeb0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
eec0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
eed0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
eee0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
eef0: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
ef00: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
ef10: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
ef20: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
ef30: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
ef40: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
ef50: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
ef60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ef70: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ef80: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
ef90: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
efa0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
efb0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
efc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
efd0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
efe0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
eff0: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
f000: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
f010: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f020: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
f030: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
f040: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
f050: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
f060: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
f070: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
f080: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
f090: 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65  pended in future
f0a0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
f0b0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
f0c0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
f0d0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
f0e0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
f0f0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
f100: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
f110: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
f120: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
f130: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
f140: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
f150: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
f160: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
f170: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
f180: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
f190: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
f1a0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
f1b0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
f1c0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
f1d0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
f1e0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
f1f0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
f200: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
f210: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
f220: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
f230: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
f240: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
f250: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f260: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
f270: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
f280: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
f290: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
f2a0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
f2b0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
f2c0: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
f2d0: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
f2e0: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
f2f0: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
f300: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
f310: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
f320: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f330: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
f340: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
f350: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
f360: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
f370: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
f380: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
f390: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
f3a0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
f3b0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
f3c0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
f3d0: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
f3e0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
f3f0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
f400: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
f410: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
f420: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
f430: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
f440: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
f450: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
f460: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
f470: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
f480: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
f490: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
f4a0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
f4b0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f4c0: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
f4d0: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
f4e0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
f4f0: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
f500: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f510: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
f520: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
f530: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
f540: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
f550: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
f560: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
f570: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
f580: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
f590: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
f5a0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
f5b0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f5c0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
f5d0: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
f5e0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
f5f0: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
f600: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
f610: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
f620: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
f630: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
f640: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
f650: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f660: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
f670: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
f680: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
f690: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
f6a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f6b0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f6c0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
f6d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
f6e0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
f6f0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
f700: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
f710: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
f720: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
f730: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
f740: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
f750: 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68   was given on th
f760: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
f770: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
f780: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
f790: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
f7a0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
f7b0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
f7c0: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
f7d0: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
f7e0: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
f7f0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f800: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
f810: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
f820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f830: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
f840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f850: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
f860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f870: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
f880: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
f890: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
f8a0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
f8b0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
f8c0: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
f8d0: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
f8e0: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
f8f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
f900: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
f910: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
f920: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
f930: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
f940: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
f950: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
f960: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
f970: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
f980: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
f990: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
f9a0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
f9b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
f9c0: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
f9d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
f9e0: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
f9f0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
fa00: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
fa10: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
fa20: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
fa30: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
fa40: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
fa50: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
fa60: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
fa70: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
fa80: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
fa90: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
faa0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
fab0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
fac0: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
fad0: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
fae0: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
faf0: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
fb00: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
fb10: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
fb20: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
fb30: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
fb40: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
fb50: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
fb60: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
fb70: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
fb80: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
fb90: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
fba0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
fbb0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
fbc0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
fbd0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fbe0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
fbf0: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
fc00: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
fc10: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
fc20: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
fc30: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fc40: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
fc50: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
fc60: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
fc70: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
fc80: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
fc90: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
fca0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fcb0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
fcc0: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
fcd0: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
fce0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
fcf0: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
fd00: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fd10: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
fd20: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
fd30: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
fd40: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
fd50: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fd60: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
fd70: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fd80: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
fd90: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
fda0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fdb0: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
fdc0: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
fdd0: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
fde0: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
fdf0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe00: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
fe10: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
fe20: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
fe30: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
fe40: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
fe50: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
fe60: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
fe70: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
fe80: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
fe90: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
fea0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
feb0: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
fec0: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
fed0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fee0: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
fef0: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
ff00: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
ff10: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
ff20: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
ff30: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
ff40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ff50: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
ff60: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
ff70: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ff80: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
ff90: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ffa0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
ffb0: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
ffc0: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
ffd0: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
ffe0: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
fff0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10000 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
10010 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
10020 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
10030 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
10040 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
10050 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
10060 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
10070 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
10080 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
10090 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
100a0 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
100b0 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
100c0 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
100d0 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
100e0 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
100f0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
10100 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
10110 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
10120 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
10130 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
10140 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
10150 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
10160 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
10170 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
10180 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
10190 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
101a0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
101b0 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
101c0 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
101d0 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
101e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
101f0 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
10200 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
10210 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
10220 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
10230 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
10240 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
10250 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
10260 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
10270 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
10280 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
10290 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
102a0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
102b0 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
102c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
102d0 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
102e0 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
102f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
10300 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
10310 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
10320 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
10330 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10340 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
10350 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
10360 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
10370 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
10380 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
10390 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
103a0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
103b0 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
103c0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
103d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
103e0 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
103f0 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
10400 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10410 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
10420 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
10430 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
10440 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
10450 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
10460 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
10470 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
10480 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
10490 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
104a0 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
104b0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
104c0 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
104d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
104e0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
104f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
10500 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
10510 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
10520 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
10530 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
10540 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
10550 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
10560 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
10570 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
10580 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
10590 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
105a0 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
105b0 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
105c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
105d0 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
105e0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
105f0 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
10600 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
10610 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
10620 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
10630 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
10640 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
10650 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
10660 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
10670 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
10680 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
10690 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
106a0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
106b0 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
106c0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
106d0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
106e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
106f0 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
10700 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
10710 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
10720 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
10730 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
10740 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10750 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
10760 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
10770 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
10780 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
10790 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
107a0 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
107b0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
107c0 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
107d0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
107e0 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
107f0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
10800 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
10810 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
10820 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
10830 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
10840 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
10850 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
10860 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
10870 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
10880 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
10890 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
108a0 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
108b0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
108c0 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
108d0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
108e0 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
108f0 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
10900 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
10910 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
10920 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10930 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
10940 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
10950 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
10960 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
10970 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
10980 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
10990 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
109a0 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
109b0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
109c0 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
109d0 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
109e0 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
109f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
10a00 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
10a10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
10a20 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
10a30 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10a40 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
10a50 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
10a60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10a70 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
10a80 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
10a90 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
10aa0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10ab0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
10ac0 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
10ad0 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
10ae0 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
10af0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
10b00 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
10b10 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
10b20 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
10b30 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
10b40 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
10b50 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10b60 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
10b70 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
10b80 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
10b90 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
10ba0 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
10bb0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
10bc0 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
10bd0 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
10be0 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
10bf0 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f   <b>The sqlite3_
10c00 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10c10 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
10c20 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63  safe. The applic
10c30 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e  ation.** must en
10c40 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
10c50 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10c60 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
10c70 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
10c80 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
10c90 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
10ca0 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a  unning.</b>.**.*
10cb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
10cc0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10cd0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
10ce0 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
10cf0 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
10d00 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
10d10 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
10d20 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
10d30 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
10d40 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10d50 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
10d60 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
10d70 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
10d80 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10d90 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
10da0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10db0 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
10dc0 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
10dd0 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
10de0 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
10df0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10e00 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
10e10 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
10e20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10e30 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
10e40 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
10e50 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
10e60 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
10e70 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10e80 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
10e90 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
10ea0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10eb0 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
10ec0 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
10ed0 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
10ee0 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
10ef0 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
10f00 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
10f10 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
10f20 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
10f30 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
10f40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
10f50 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
10f60 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
10f70 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
10f80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10f90 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
10fa0 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
10fb0 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
10fc0 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
10fd0 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
10fe0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
10ff0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
11000 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
11010 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
11020 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
11030 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
11040 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11050 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
11060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
11070 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
11080 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
11090 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
110a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
110b0 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
110c0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
110d0 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
110e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
110f0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
11100 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
11110 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11120 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
11130 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
11140 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
11150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11160 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
11170 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11180 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
11190 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
111a0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
111b0 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
111c0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
111d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
111e0 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
111f0 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
11200 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
11210 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
11220 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
11230 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
11240 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
11250 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
11260 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
11270 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
11280 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
11290 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
112a0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
112b0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
112c0 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
112d0 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
112e0 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
112f0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
11300 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e  uccessful..*/.in
11310 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
11320 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
11330 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
11340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
11350 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
11360 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
11370 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
11380 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
11390 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
113a0 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
113b0 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
113c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
113d0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
113e0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
113f0 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
11400 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
11410 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
11420 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
11430 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
11440 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
11450 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
11460 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11470 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
11480 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11490 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
114a0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
114b0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
114c0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
114d0 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
114e0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
114f0 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
11500 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
11510 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
11520 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11530 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
11540 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
11550 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
11560 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
11570 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
11580 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
11590 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
115a0 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
115b0 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
115c0 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
115d0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
115e0 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
115f0 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
11600 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
11610 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
11620 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
11630 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
11640 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
11650 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
11660 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
11670 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
11680 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
11690 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
116a0 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
116b0 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
116c0 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
116d0 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
116e0 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
116f0 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
11700 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
11710 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
11720 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
11730 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
11740 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11750 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
11760 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
11770 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
11780 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
11790 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
117a0 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
117b0 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
117c0 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
117d0 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
117e0 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
117f0 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
11800 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
11810 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
11820 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
11830 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
11840 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
11850 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
11860 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
11870 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
11880 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
11890 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
118a0 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
118b0 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
118c0 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
118d0 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
118e0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
118f0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
11900 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
11910 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
11920 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
11930 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
11940 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
11950 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
11960 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
11970 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
11980 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
11990 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
119a0 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
119b0 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
119c0 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
119d0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
119e0 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
119f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
11a00 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
11a10 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
11a20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
11a30 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
11a40 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
11a50 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
11a60 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
11a70 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
11a80 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
11a90 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
11aa0 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
11ab0 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
11ac0 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
11ad0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
11ae0 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
11af0 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
11b00 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
11b10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
11b20 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
11b30 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
11b40 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
11b50 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
11b60 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
11b70 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
11b80 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
11b90 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
11ba0 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
11bb0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11bc0 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d  cator.  For exam
11bd0 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
11be0 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
11bf0 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
11c00 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
11c10 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
11c20 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
11c30 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
11c40 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
11c50 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
11c60 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11c70 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
11c80 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
11c90 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
11ca0 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
11cb0 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
11cc0 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
11cd0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
11ce0 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
11cf0 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
11d00 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
11d10 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
11d20 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
11d30 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
11d40 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
11d50 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
11d60 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
11d70 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
11d80 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
11d90 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
11da0 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
11db0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
11dc0 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
11dd0 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
11de0 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
11df0 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
11e00 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
11e10 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
11e20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
11e30 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
11e40 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
11e50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
11e60 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11e70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11e80 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
11e90 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
11ea0 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
11eb0 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
11ec0 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
11ed0 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
11ee0 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
11ef0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11f00 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
11f10 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
11f20 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
11f30 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
11f40 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
11f50 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
11f60 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
11f70 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
11f80 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
11f90 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
11fa0 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
11fb0 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
11fc0 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
11fd0 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
11fe0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
11ff0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
12000 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
12010 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
12020 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
12030 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
12040 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
12050 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
12060 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12070 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
12080 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
12090 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
120a0 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
120b0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
120c0 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
120d0 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
120e0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
120f0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
12100 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
12110 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
12120 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
12130 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12140 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
12150 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
12160 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
12170 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
12180 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
12190 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
121a0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
121b0 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
121c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
121d0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
121e0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
121f0 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
12200 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
12210 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
12220 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
12230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
12240 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
12250 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
12260 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
12270 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
12280 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
12290 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
122a0 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
122b0 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
122c0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
122d0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
122e0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
122f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
12300 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
12310 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
12320 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
12330 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12340 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
12350 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
12360 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
12370 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
12380 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
12390 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
123a0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
123b0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
123c0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
123d0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
123e0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
123f0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
12400 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
12410 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
12420 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
12430 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
12440 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
12450 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
12460 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
12470 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
12480 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
12490 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
124a0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
124b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
124c0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
124d0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
124e0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
124f0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
12500 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12510 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
12520 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12530 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12540 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12550 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12560 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12570 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
12580 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
12590 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
125a0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
125b0 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
125c0 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
125d0 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
125e0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
125f0 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
12600 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
12610 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12620 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
12630 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
12640 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
12650 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12660 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
12670 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
12680 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
12690 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
126a0 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
126b0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
126c0 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
126d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
126e0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
126f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
12700 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12710 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
12720 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
12730 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
12740 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12750 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12760 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12770 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12780 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12790 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
127a0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
127b0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
127c0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
127d0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
127e0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
127f0 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
12800 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12810 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
12820 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
12830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12840 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12850 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
12860 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
12870 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
12880 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
12890 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
128a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
128b0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
128c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
128d0 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
128e0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
128f0 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
12900 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
12910 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
12920 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
12930 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
12940 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
12950 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
12960 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
12970 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12980 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
12990 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
129a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
129b0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
129c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
129d0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
129e0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
129f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12a00 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12a10 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
12a20 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
12a30 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12a40 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
12a50 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
12a60 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
12a70 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12a80 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
12a90 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
12aa0 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
12ab0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
12ac0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12ad0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12ae0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12af0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
12b00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
12b10 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
12b20 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
12b30 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
12b40 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
12b50 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
12b60 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
12b70 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
12b80 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
12b90 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
12ba0 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
12bb0 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
12bc0 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
12bd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
12be0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12bf0 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
12c00 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
12c10 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
12c20 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
12c30 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12c40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
12c50 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
12c60 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
12c70 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
12c80 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
12c90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12ca0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
12cb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
12cc0 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
12cd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
12ce0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
12cf0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
12d00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
12d10 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
12d20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
12d30 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
12d40 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
12d50 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
12d60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12d70 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12d80 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12d90 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12da0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12db0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12dc0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
12dd0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
12de0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
12df0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
12e00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12e10 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
12e20 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
12e30 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12e40 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
12e50 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
12e60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12e70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
12e80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12e90 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
12ea0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12eb0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
12ec0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
12ed0 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  FIG_MALLOC optio
12ee0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12ef0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
12f00 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
12f10 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
12f20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12f30 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12f40 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
12f50 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
12f60 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
12f70 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
12f80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12f90 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
12fa0 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
12fb0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
12fc0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
12fd0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
12fe0 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
12ff0 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
13000 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
13010 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
13020 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13030 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
13040 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
13050 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13060 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
13070 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13080 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13090 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
130a0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
130b0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
130c0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
130d0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74  IG_GETMALLOC opt
130e0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
130f0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
13100 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
13110 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
13120 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13130 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
13140 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
13150 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13160 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
13170 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
13180 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
13190 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
131a0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
131b0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
131c0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
131d0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
131e0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
131f0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
13200 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
13210 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
13220 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
13230 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
13240 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
13250 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
13260 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
13270 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13280 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
13290 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
132a0 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
132b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
132c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
132d0 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61  STATUS option ta
132e0 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
132f0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
13300 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20  .** interpreted 
13310 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68  as a boolean, wh
13320 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
13330 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
13340 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d  ection of.** mem
13350 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
13360 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
13370 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
13380 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13390 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20  re.** disabled, 
133a0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
133b0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
133c0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
133d0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
133e0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
133f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
13400 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
13410 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
13420 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
13430 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
13440 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
13450 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
13460 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29  lite3_status64()
13470 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
13480 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
13490 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
134a0 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
134b0 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
134c0 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
134d0 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
134e0 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
134f0 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
13500 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
13510 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
13520 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
13530 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
13540 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13550 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13560 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
13570 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
13580 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13590 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
135a0 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73  SCRATCH option s
135b0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
135c0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a  c memory buffer.
135d0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
135e0 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74  an use for scrat
135f0 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68  ch memory.  ^(Th
13600 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13610 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51  guments.** to SQ
13620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13630 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  TCH:  A pointer 
13640 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
13650 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
13660 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
13670 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
13680 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
13690 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
136a0 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
136b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
136c0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
136d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
136e0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
136f0 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65  ns (N).)^.** The
13700 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13710 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
13720 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
13730 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
13740 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
13750 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
13760 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
13770 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20  ll not use more 
13780 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68  than one scratch
13790 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
137a0 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ead..** ^SQLite 
137b0 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65  will never reque
137c0 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66  st a scratch buf
137d0 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
137e0 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
137f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
13800 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  ge size..** ^If 
13810 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
13820 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
13830 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
13840 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
13850 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
13860 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13870 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
13880 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13890 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
138a0 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
138b0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a  ory needed.<p>.*
138c0 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c  * ^When the appl
138d0 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73  ication provides
138e0 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73   any amount of s
138f0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73  cratch memory us
13900 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  ing.** SQLITE_CO
13910 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51  NFIG_SCRATCH, SQ
13920 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65  Lite avoids unne
13930 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a  cessary large.**
13940 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13950 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e  |heap allocation
13960 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20  s]..** This can 
13970 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f  help [Robson pro
13980 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72  of|prevent memor
13990 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
139a0 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65  lures] due to he
139b0 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74  ap.** fragmentat
139c0 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72  ion in low-memor
139d0 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  y embedded syste
139e0 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ms..** </dd>.**.
139f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13a00 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
13a10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13a20 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
13a30 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13a40 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13a50 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63  ACHE option spec
13a60 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70  ifies a memory p
13a70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ool.** that SQLi
13a80 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74  te can use for t
13a90 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
13aa0 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
13ab0 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20  default page.** 
13ac0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
13ad0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
13ae0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13af0 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tion is a no-op 
13b00 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
13b10 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
13b20 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13b30 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
13b40 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
13b50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13b60 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65  ]..** ^There are
13b70 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
13b80 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
13b90 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70  G_PAGECACHE: A p
13ba0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62  ointer to.** 8-b
13bb0 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  yte aligned memo
13bc0 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73  ry (pMem), the s
13bd0 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
13be0 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29   cache line (sz)
13bf0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d  ,.** and the num
13c00 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e  ber of cache lin
13c10 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
13c20 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
13c30 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
13c40 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
13c50 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
13c60 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
13c70 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35  tween 512 and 65
13c80 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65  536) plus some e
13c90 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65  xtra bytes for e
13ca0 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
13cb0 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72  er.  ^The number
13cc0 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20   of extra bytes 
13cd0 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61  needed by the pa
13ce0 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e  ge header.** can
13cf0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
13d00 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  sing [SQLITE_CON
13d10 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
13d20 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72  ]..** ^It is har
13d30 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
13d40 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
13d50 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ory,.** for the 
13d60 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  sz parameter to 
13d70 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e  be larger than n
13d80 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 70  ecessary.  The p
13d90 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  Mem.** argument 
13da0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
13db0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
13dc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13dd0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
13de0 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f  ed block of memo
13df0 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ry of at least s
13e00 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72  z*N bytes, other
13e10 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65  wise.** subseque
13e20 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  nt behavior is u
13e30 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68  ndefined..** ^Wh
13e40 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e  en pMem is not N
13e50 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
13e60 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 74   strive to use t
13e70 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
13e80 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79  ed.** to satisfy
13e90 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 64   page cache need
13ea0 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20  s, falling back 
13eb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
13ec0 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61  oc()] if.** a pa
13ed0 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73  ge cache line is
13ee0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20   larger than sz 
13ef0 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20  bytes or if all 
13f00 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66  of the pMem buff
13f10 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74  er.** is exhaust
13f20 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20  ed..** ^If pMem 
13f30 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73  is NULL and N is
13f40 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
13f50 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
13f60 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73  nnection.** does
13f70 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b   an initial bulk
13f80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
13f90 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13fa0 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  y.** from [sqlit
13fb0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66  e3_malloc()] suf
13fc0 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61  ficient for N ca
13fd0 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69  che lines if N i
13fe0 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a  s positive or.**
13ff0 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65   of -1024*N byte
14000 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  s if N is negati
14010 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69  ve, . ^If additi
14020 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
14030 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
14040 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
14050 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
14060 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c  he initial.** al
14070 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53  location, then S
14080 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
14090 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
140a0 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20   separately for 
140b0 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e  each.** addition
140c0 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c  al cache line. <
140d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
140e0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
140f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14100 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
14110 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14120 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
14130 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
14140 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
14150 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53  uffer .** that S
14160 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66  QLite will use f
14170 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
14180 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
14190 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a  ocation needs.**
141a0 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
141b0 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53  ovided for by [S
141c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
141d0 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51  ATCH] and.** [SQ
141e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
141f0 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20  CACHE]..** ^The 
14200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14210 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  AP option is onl
14220 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
14230 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14240 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72  d.** with either
14250 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
14260 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c  MEMSYS3] or [SQL
14270 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
14280 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  S5] and returns.
14290 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
142a0 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68  ] if invoked oth
142b0 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72  erwise..** ^Ther
142c0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
142d0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
142e0 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20  CONFIG_HEAP:.** 
142f0 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
14300 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
14310 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
14320 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
14330 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
14340 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
14350 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14360 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
14370 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
14380 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
14390 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
143a0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
143b0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
143c0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
143d0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
143e0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
143f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
14400 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
14410 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
14420 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
14430 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
14440 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
14450 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
14460 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  LL then the alte
14470 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
14480 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
14490 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
144a0 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
144b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
144c0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
144d0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
144e0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
144f0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
14500 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
14510 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
14520 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
14530 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
14540 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
14550 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
14560 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
14570 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
14580 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
14590 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
145a0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
145b0 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
145c0 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
145d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
145e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
145f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14600 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
14610 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14620 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14630 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14640 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14650 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f  which is a.** po
14660 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
14670 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
14680 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14690 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
146a0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
146b0 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61  pecifies alterna
146c0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
146d0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
146e0 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70   be used.** in p
146f0 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72  lace the mutex r
14700 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
14710 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
14720 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
14730 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
14740 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
14750 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14760 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
14770 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
14780 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
14790 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
147a0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
147b0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
147c0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
147d0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
147e0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
147f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14800 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
14810 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
14820 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
14830 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
14840 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
14850 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14860 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14870 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14880 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
14890 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
148a0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
148b0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
148c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
148d0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
148e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
148f0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
14900 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14910 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14920 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
14930 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14940 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
14950 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14960 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
14970 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
14980 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
14990 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
149a0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
149b0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
149c0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
149d0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
149e0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
149f0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
14a00 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
14a10 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
14a20 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
14a30 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
14a40 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
14a50 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
14a60 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
14a70 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
14a80 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
14a90 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
14aa0 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
14ab0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14ac0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
14ad0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
14ae0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
14af0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
14b00 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
14b10 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
14b20 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
14b30 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
14b40 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
14b50 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
14b60 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14b70 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
14b80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
14b90 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
14ba0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
14bb0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
14bc0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
14bd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14be0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
14bf0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14c00 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
14c10 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14c20 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14c30 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SIDE option take
14c40 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
14c50 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a  that determine.*
14c60 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69  * the default si
14c70 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  ze of lookaside 
14c80 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b  memory on each [
14c90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14ca0 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
14cb0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
14cc0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
14cd0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
14ce0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
14cf0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
14d00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
14d10 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
14d20 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
14d30 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51  nection.)^  ^(SQ
14d40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14d50 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68  ASIDE.** sets th
14d60 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  e <i>default</i>
14d70 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
14d80 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
14d90 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
14da0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73  .** option to [s
14db0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
14dc0 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
14dd0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
14de0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
14df0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
14e00 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
14e10 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
14e20 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14e30 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
14e40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14e50 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
14e60 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14e70 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
14e80 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14e90 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14ea0 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
14eb0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
14ec0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14ed0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
14ee0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
14ef0 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72  ies.** the inter
14f00 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d  face to a custom
14f10 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
14f20 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  ementation.)^.**
14f30 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
14f40 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
14f50 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14f60 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f  hods2] object.</
14f70 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14f80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14f90 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
14fa0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14fb0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14fc0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14fd0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
14fe0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14ff0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15000 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
15010 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
15020 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15030 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
15040 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a  Lite copies of.*
15050 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61  * the current pa
15060 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
15070 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
15080 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
15090 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
150a0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
150b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
150c0 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
150d0 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
150e0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73  IG_LOG option is
150f0 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
15100 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  re the SQLite.**
15110 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c   global [error l
15120 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51  og]..** (^The SQ
15130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15140 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
15150 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
15160 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
15170 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
15180 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
15190 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
151a0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
151b0 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
151c0 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
151d0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
151e0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
151f0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
15200 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
15210 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
15220 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
15230 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
15240 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
15250 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
15260 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
15270 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
15280 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
15290 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
152a0 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
152b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
152c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
152d0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
152e0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
152f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
15300 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
15310 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
15320 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
15330 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
15340 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
15350 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15360 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
15370 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
15380 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
15390 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
153a0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
153b0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
153c0 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
153d0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
153e0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
153f0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
15400 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
15410 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
15420 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
15430 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
15440 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
15450 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
15460 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
15470 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
15480 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
15490 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
154a0 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
154b0 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
154c0 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
154d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
154e0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
154f0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
15500 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
15510 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
15520 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
15530 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
15540 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
15550 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
15560 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
15570 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15580 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
15590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
155a0 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
155b0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f  ITE_CONFIG_URI o
155c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
155d0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
155e0 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66   type int..** If
155f0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
15600 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
15610 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
15620 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
15630 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74  er is zero,.** t
15640 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
15650 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
15660 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
15670 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
15680 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64  bally.** enabled
15690 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20  , all filenames 
156a0 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
156b0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
156c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
156d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
156e0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
156f0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
15700 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
15710 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
15720 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
15730 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
15740 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
15750 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
15760 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
15770 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15780 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
15790 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
157a0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
157b0 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
157c0 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
157d0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
157e0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
157f0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
15800 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
15810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15820 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
15830 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
15840 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
15850 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
15860 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
15870 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
15880 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
15890 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
158a0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
158b0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
158c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
158d0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
158e0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
158f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15900 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15910 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  N.** <dd>^The SQ
15920 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15930 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
15940 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15950 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a  ingle integer.**
15960 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15970 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
15980 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  s a boolean in o
15990 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
159a0 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  r disable.** the
159b0 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
159c0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
159d0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
159e0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
159f0 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  izer..** ^The de
15a00 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
15a10 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
15a20 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
15a30 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
15a40 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
15a50 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
15a60 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
15a70 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
15a80 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
15a90 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
15aa0 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
15ab0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
15ac0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
15ad0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
15ae0 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
15af0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
15b00 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
15b10 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
15b20 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65  lfunction.** whe
15b30 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
15b40 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
15b50 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
15b60 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
15b70 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
15b80 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
15b90 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
15ba0 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
15bb0 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
15bc0 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
15bd0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
15be0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
15bf0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15c00 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
15c10 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15c20 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
15c30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15c40 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
15c50 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
15c60 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
15c70 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
15c80 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
15c90 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
15ca0 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
15cb0 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
15cc0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
15cd0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
15ce0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
15cf0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15d00 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15d10 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15d20 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
15d30 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
15d40 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15d50 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
15d60 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
15d70 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
15d80 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
15d90 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
15da0 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
15db0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
15dc0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
15dd0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
15de0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
15df0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
15e00 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
15e10 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
15e20 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
15e30 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
15e40 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
15e50 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
15e60 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
15e70 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
15e80 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
15e90 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
15ea0 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
15eb0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15ec0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
15ed0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
15ee0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
15ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
15f00 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
15f10 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
15f20 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
15f30 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
15f40 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
15f50 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
15f60 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
15f70 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
15f80 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
15f90 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
15fa0 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
15fb0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
15fc0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
15fd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
15fe0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
15ff0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
16000 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
16010 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
16020 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
16030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
16040 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
16050 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16060 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
16070 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
16080 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
16090 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
160a0 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
160b0 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
160c0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
160d0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
160e0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
160f0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
16100 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
16110 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
16120 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
16130 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16140 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
16150 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
16160 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
16170 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c  SIZE.** <dd>^SQL
16180 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
16190 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
161a0 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
161b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
161c0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
161d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
161e0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
161f0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
16200 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
16210 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
16220 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
16230 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
16240 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  imit..** ^The de
16250 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
16260 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
16270 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
16280 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
16290 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
162a0 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
162b0 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
162c0 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
162d0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
162e0 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
162f0 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78  trol.  ^(The max
16300 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
16310 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62  p size.** will b
16320 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  e silently trunc
16330 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72  ated if necessar
16340 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65  y so that it doe
16350 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65  s not exceed the
16360 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
16370 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69   maximum mmap si
16380 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  ze set by the.**
16390 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41   [SQLITE_MAX_MMA
163a0 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d  P_SIZE] compile-
163b0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a  time option.)^.*
163c0 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67  * ^If either arg
163d0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70  ument to this op
163e0 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65  tion is negative
163f0 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75  , then that argu
16400 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67  ment is.** chang
16410 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c  ed to its compil
16420 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
16430 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16440 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16450 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
16460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16470 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64  2_HEAPSIZE.** <d
16480 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16490 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
164a0 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  IZE option is on
164b0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
164c0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
164d0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
164e0 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  s with the [SQLI
164f0 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
16500 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
16510 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e  acro.** defined.
16520 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   ^SQLITE_CONFIG_
16530 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74  WIN32_HEAPSIZE t
16540 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e  akes a 32-bit un
16550 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76  signed integer v
16560 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65  alue.** that spe
16570 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d  cifies the maxim
16580 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63  um size of the c
16590 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a  reated heap..**.
165a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
165b0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
165c0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
165d0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
165e0 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  RSZ.** <dd>^The 
165f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16600 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f  ACHE_HDRSZ optio
16610 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16620 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
16630 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
16640 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
16650 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74  nd writes into t
16660 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20  hat integer the 
16670 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a  number of extra.
16680 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67  ** bytes per pag
16690 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  e required for e
166a0 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c  ach page in [SQL
166b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
166c0 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d  ACHE]..** The am
166d0 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70  ount of extra sp
166e0 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e  ace required can
166f0 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e   change dependin
16700 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  g on the compile
16710 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61  r,.** target pla
16720 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74  tform, and SQLit
16730 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  e version..**.**
16740 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16750 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _PMASZ]].** <dt>
16760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
16770 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ASZ.** <dd>^The 
16780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
16790 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ASZ option takes
167a0 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
167b0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
167c0 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  an unsigned inte
167d0 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65  ger and sets the
167e0 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69   "Minimum PMA Si
167f0 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74  ze" for the mult
16800 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72  ithreaded.** sor
16810 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65  ter to that inte
16820 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ger.  The defaul
16830 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69  t minimum PMA Si
16840 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65  ze is set by the
16850 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54  .** [SQLITE_SORT
16860 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c  ER_PMASZ] compil
16870 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20  e-time option.  
16880 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20  New threads are 
16890 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68  launched.** to h
168a0 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70  elp with sort op
168b0 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75  erations when mu
168c0 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74  ltithreaded sort
168d0 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65  ing.** is enable
168e0 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52  d (using the [PR
168f0 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f  AGMA threads] co
16900 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61  mmand) and the a
16910 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74  mount of content
16920 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64  .** to be sorted
16930 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67   exceeds the pag
16940 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65  e size times the
16950 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a   minimum of the.
16960 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65  ** [PRAGMA cache
16970 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61  _size] setting a
16980 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a  nd this value..*
16990 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
169a0 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
169b0 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  ILL]].** <dt>SQL
169c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
169d0 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64  RNL_SPILL.** <dd
169e0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
169f0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
16a00 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  LL option takes 
16a10 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
16a20 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f  er which.** beco
16a30 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65  mes the [stateme
16a40 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c  nt journal] spil
16a50 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68  l-to-disk thresh
16a60 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65  old.  .** [State
16a70 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61  ment journals] a
16a80 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  re held in memor
16a90 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69  y until their si
16aa0 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a  ze (in bytes).**
16ab0 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68   exceeds this th
16ac0 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63  reshold, at whic
16ad0 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65  h point they are
16ae0 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
16af0 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74  ..** Or if the t
16b00 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20  hreshold is -1, 
16b10 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
16b20 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65  ls are always he
16b30 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c  ld.** exclusivel
16b40 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  y in memory..** 
16b50 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65  Since many state
16b60 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65  ment journals ne
16b70 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65  ver become large
16b80 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70  , setting the sp
16b90 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64  ill.** threshold
16ba0 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68   to a value such
16bb0 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72   as 64KiB can gr
16bc0 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65  eatly reduce the
16bd0 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f   amount of.** I/
16be0 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75  O required to su
16bf0 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20  pport statement 
16c00 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  rollback..** The
16c10 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
16c20 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20  or this setting 
16c30 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  is controlled by
16c40 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16c50 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20  STMTJRNL_SPILL] 
16c60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16c70 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ion..** </dl>.*/
16c80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16c90 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
16ca0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
16cb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16cc0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16cd0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
16ce0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16cf0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
16d00 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
16d10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16d20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
16d30 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
16d40 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16d50 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16d60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16d70 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
16d80 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
16d90 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16da0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
16db0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
16dc0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16dd0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
16de0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16df0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
16e00 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
16e10 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
16e20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16e30 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
16e40 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
16e50 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
16e60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16e70 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
16e80 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
16e90 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
16ea0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
16eb0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
16ec0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16ed0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
16ee0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16ef0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
16f00 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
16f10 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
16f20 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
16f30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
16f40 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
16f50 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
16f60 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
16f70 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
16f80 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
16f90 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16fb0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
16fc0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
16fd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16fe0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
16ff0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
17000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17010 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
17020 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
17030 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
17040 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
17050 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
17060 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
17070 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17080 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
17090 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
170a0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
170b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
170c0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
170d0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
170e0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
170f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17100 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
17110 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
17120 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
17130 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17140 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
17150 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
17160 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
17170 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17180 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
17190 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
171a0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
171b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
171c0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
171d0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
171e0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
171f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17200 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17210 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
17220 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
17230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17240 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
17250 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
17260 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
17270 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
17280 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17290 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
172a0 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
172b0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
172c0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
172d0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
172e0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
172f0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
17300 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
17310 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
17320 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17330 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
17340 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
17350 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17360 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
17370 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
17380 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
17390 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
173a0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
173b0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
173c0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
173d0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
173e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
173f0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
17400 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
17410 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
17420 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
17430 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
17440 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17450 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
17460 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
17470 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
17480 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17490 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
174a0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
174b0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
174c0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
174d0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
174e0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
174f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
17500 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
17510 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
17520 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17530 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
17540 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17550 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
17560 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
17570 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
17580 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
17590 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
175a0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
175b0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
175c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
175d0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
175e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
175f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
17600 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
17610 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
17620 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
17630 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
17640 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
17650 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
17660 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17670 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
17680 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
17690 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
176a0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
176b0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
176c0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
176d0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
176e0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
176f0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
17700 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
17710 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
17720 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
17730 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
17740 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
17750 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
17760 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
17770 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
17780 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
17790 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
177a0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
177b0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
177c0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
177d0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
177e0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
177f0 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
17800 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
17810 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
17820 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
17830 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
17840 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
17850 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
17860 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
17870 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
17880 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
17890 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
178a0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
178b0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
178c0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
178d0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
178e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
178f0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
17900 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
17910 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
17920 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
17930 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
17940 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
17950 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
17960 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
17970 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
17980 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
17990 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
179a0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
179b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
179c0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
179d0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
179e0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
179f0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
17a00 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
17a10 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
17a20 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
17a30 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
17a40 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
17a50 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
17a60 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
17a70 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
17a80 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17a90 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17aa0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
17ab0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
17ac0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
17ad0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
17ae0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
17af0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
17b00 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
17b10 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
17b20 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
17b30 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
17b40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
17b50 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
17b60 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
17b70 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
17b80 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
17b90 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
17ba0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
17bb0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
17bc0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
17bd0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
17be0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17bf0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
17c00 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
17c10 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
17c20 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
17c30 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
17c40 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
17c50 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
17c60 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
17c70 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
17c80 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
17c90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
17ca0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
17cb0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
17cc0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
17cd0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
17ce0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
17cf0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17d00 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
17d10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17d20 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
17d30 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
17d40 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
17d50 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
17d60 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
17d70 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17d80 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17d90 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
17da0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
17db0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
17dc0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
17dd0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
17de0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
17df0 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
17e00 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
17e10 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
17e20 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
17e30 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
17e40 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
17e50 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
17e60 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
17e70 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
17e80 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
17e90 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
17ea0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
17eb0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
17ec0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
17ed0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
17ee0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
17ef0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
17f00 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
17f10 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
17f20 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
17f30 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
17f40 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17f50 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f  FTS3_TOKENIZER</
17f60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17f70 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17f80 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17f90 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72  sable the two-ar
17fa0 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f  gument.** versio
17fb0 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74  n of the [fts3_t
17fc0 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63  okenizer()] func
17fd0 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61  tion which is pa
17fe0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54  rt of the.** [FT
17ff0 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65  S3] full-text se
18000 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65  arch engine exte
18010 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  nsion..** There 
18020 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18030 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18040 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
18050 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
18060 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
18070 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74   0 to disable ft
18080 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f  s3_tokenizer() o
18090 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  r.** positive to
180a0 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b   enable fts3_tok
180b0 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61  enizer() or nega
180c0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
180d0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
180e0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
180f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18100 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18110 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18120 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18130 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18140 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66  dicate whether f
18150 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73  ts3_tokenizer is
18160 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18170 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
18180 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18190 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
181a0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
181b0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
181c0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
181d0 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  ew setting is no
181e0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
181f0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
18200 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
18210 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
18220 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENSION</dt>.** <
18230 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18240 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
18250 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
18260 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
18270 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
18280 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65  interface indepe
18290 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b  ndently of the [
182a0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
182b0 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  ] SQL function..
182c0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
182d0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
182e0 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61  nsion()] API ena
182f0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
18300 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41   both the.** C-A
18310 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  PI [sqlite3_load
18320 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e  _extension()] an
18330 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
18340 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  on [load_extensi
18350 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  on()]..** There 
18360 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18370 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18380 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  ts..** When the 
18390 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
183a0 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  o this interface
183b0 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79   is 1, then only
183c0 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a   the C-API is.**
183d0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65   enabled and the
183e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
183f0 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20  mains disabled. 
18400 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72   If the first ar
18410 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69  gument to.** thi
18420 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30  s interface is 0
18430 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20  , then both the 
18440 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51  C-API and the SQ
18450 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64  L function are d
18460 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74  isabled..** If t
18470 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18480 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f  t is -1, then no
18490 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64   changes are mad
184a0 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69  e to state of ei
184b0 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50  ther the.** C-AP
184c0 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e  I or the SQL fun
184d0 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65  ction..** The se
184e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
184f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18500 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
18510 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
18520 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
18530 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73  icate whether [s
18540 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18550 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
18560 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65  ce.** is disable
18570 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c  d or enabled fol
18580 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
18590 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
185a0 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62  rameter may.** b
185b0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
185c0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
185d0 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20  the new setting 
185e0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
185f0 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  back..** </dd>.*
18600 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18610 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e  DBCONFIG_MAINDBN
18620 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  AME</dt>.** <dd>
18630 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18640 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
18650 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18660 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a  "main" database.
18670 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65  ** schema.  ^The
18680 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69   sole argument i
18690 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
186a0 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73   constant UTF8 s
186b0 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77  tring.** which w
186c0 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e  ill become the n
186d0 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69  ew schema name i
186e0 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e  n place of "main
186f0 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64  ".  ^SQLite.** d
18700 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63  oes not make a c
18710 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d  opy of the new m
18720 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  ain schema name 
18730 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61  string, so the a
18740 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
18750 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
18760 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  he argument pass
18770 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43  ed into this DBC
18780 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20  ONFIG option is 
18790 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74  unchanged.** unt
187a0 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 74  il after the dat
187b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
187c0 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64   closes..** </dd
187d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
187e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
187f0 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74  KPT_ON_CLOSE</dt
18800 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c  >.** <dd> Usuall
18810 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  y, when a databa
18820 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69  se in wal mode i
18830 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61  s closed or deta
18840 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20  ched from a .** 
18850 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c  database handle,
18860 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69   SQLite checks i
18870 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e  f this will mean
18880 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20   that there are 
18890 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65  now no .** conne
188a0 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f  ctions at all to
188b0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49   the database. I
188c0 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d  f so, it perform
188d0 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a  s a checkpoint .
188e0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66  ** operation bef
188f0 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20  ore closing the 
18900 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73  connection. This
18910 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75   option may be u
18920 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69  sed to.** overri
18930 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75  de this behaviou
18940 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72  r. The first par
18950 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
18960 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a   this operation.
18970 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ** is an integer
18980 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64   - non-zero to d
18990 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e  isable checkpoin
189a0 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20  ts-on-close, or 
189b0 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66  zero (the.** def
189c0 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20  ault) to enable 
189d0 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64  them. The second
189e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
189f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18a00 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68  teger.** into wh
18a10 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30  ich is written 0
18a20 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
18a30 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70  e whether checkp
18a40 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a  oints-on-close.*
18a50 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61  * have been disa
18a60 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79  bled - 0 if they
18a70 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65   are not disable
18a80 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65  d, 1 if they are
18a90 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
18aa0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18ab0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
18ac0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54  </dt>.** <dd>^(T
18ad0 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
18ae0 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f  IG_ENABLE_QPSG o
18af0 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20  ption activates 
18b00 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a  or deactivates.*
18b10 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c 61  * the [query pla
18b20 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20 67  nner stability g
18b30 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47 29  uarantee] (QPSG)
18b40 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50 53 47  .  When the QPSG
18b50 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61   is active,.** a
18b60 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72   single SQL quer
18b70 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  y statement will
18b80 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20   always use the 
18b90 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 72  same algorithm r
18ba0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
18bb0 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64  values of [bound
18bc0 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20   parameters].)^ 
18bd0 54 68 65 20 51 50 53 47 20 64 69 73 61 62 6c 65  The QPSG disable
18be0 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70 74  s some query opt
18bf0 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68  imizations.** th
18c00 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76  at look at the v
18c10 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20 70  alues of bound p
18c20 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63 68  arameters, which
18c30 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71   can make some q
18c40 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72  ueries.** slower
18c50 2e 20 20 42 75 74 20 74 68 65 20 51 50 53 47 20  .  But the QPSG 
18c60 68 61 73 20 74 68 65 20 61 64 76 61 6e 74 61 67  has the advantag
18c70 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69 63  e of more predic
18c80 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20  table behavior. 
18c90 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50 53   With.** the QPS
18ca0 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74 65  G active, SQLite
18cb0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65   will always use
18cc0 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79 20   the same query 
18cd0 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65 6c  plan in the fiel
18ce0 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65 64  d as.** was used
18cf0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
18d00 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 3c  in the lab..** <
18d10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
18d20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
18d30 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
18d40 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  DBNAME          
18d50 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20    1000 /* const 
18d60 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  char* */.#define
18d70 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18d80 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
18d90 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76         1001 /* v
18da0 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
18db0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18dc0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
18dd0 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30  KEY           10
18de0 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  02 /* int int* *
18df0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18e00 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18e10 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
18e20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1003 /* int int*
18e30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18e50 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
18e60 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e  R 1004 /* int in
18e70 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18e80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18e90 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
18ea0 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20  ION 1005 /* int 
18eb0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18ec0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18ed0 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
18ee0 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e        1006 /* in
18ef0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18f00 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18f10 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20  G_ENABLE_QPSG   
18f20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20          1007 /* 
18f30 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
18f40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
18f50 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
18f60 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
18f70 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
18f80 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18f90 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
18fa0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
18fb0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
18fc0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
18fd0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
18fe0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
18ff0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
19000 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
19010 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
19020 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
19030 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
19040 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
19050 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
19060 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
19070 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
19080 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
19090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
190a0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
190b0 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
190c0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
190d0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
190e0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
190f0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
19100 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
19110 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
19120 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
19130 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
19140 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
19150 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
19160 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
19170 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
19180 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
19190 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
191a0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
191b0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
191c0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
191d0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
191e0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
191f0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
19200 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
19210 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
19220 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
19230 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
19240 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
19250 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
19260 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
19270 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19280 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19290 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
192a0 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ce usually retur
192b0 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
192c0 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  f.** the most re
192d0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
192e0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
192f0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
19300 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
19310 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
19320 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73  nnection D. ^Ins
19330 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
19340 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
19350 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f   are not.** reco
19360 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63  rded. ^If no suc
19370 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
19380 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
19390 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63  les have ever oc
193a0 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68  curred .** on th
193b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
193c0 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71  ction D, then sq
193d0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
193e0 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
193f0 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a  ns .** zero..**.
19400 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65  ** As well as be
19410 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69  ing set automati
19420 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72  cally as rows ar
19430 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
19440 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
19450 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
19460 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
19470 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73  unction may be s
19480 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79  et explicitly by
19490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
194a0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
194b0 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  id()].**.** Some
194c0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
194d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
194e0 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69  ay INSERT rows i
194f0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
19500 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63   as.** part of c
19510 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e  ommitting a tran
19520 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f  saction (e.g. to
19530 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75   flush data accu
19540 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72  mulated in memor
19550 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49  y.** to disk). I
19560 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73  n this case subs
19570 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
19580 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
19590 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
195a0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
195b0 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c  h these internal
195c0 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f   INSERT operatio
195d0 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20  ns, which leads 
195e0 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69  to .** unintuiti
195f0 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74  ve results. Virt
19600 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
19610 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64  entations that d
19620 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64  o write to rowid
19630 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68  .** tables in th
19640 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64  is way can avoid
19650 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79   this problem by
19660 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f   restoring the o
19670 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69  riginal .** rowi
19680 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73  d value using [s
19690 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
196a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
196b0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
196c0 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20   .** control to 
196d0 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20  the user..**.** 
196e0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
196f0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
19700 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68   trigger then th
19710 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
19720 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b  .** return the [
19730 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
19740 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f  serted row as lo
19750 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
19760 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67  r is .** running
19770 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67  . Once the trigg
19780 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c  er program ends,
19790 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
197a0 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
197b0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
197c0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
197d0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
197e0 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a  r was fired.)^.*
197f0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
19800 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
19810 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
19820 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
19830 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
19840 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
19850 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
19860 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19870 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
19880 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
19890 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
198a0 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
198b0 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
198c0 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
198d0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
198e0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
198f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
19900 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
19910 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
19920 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
19930 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
19940 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
19950 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
19960 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
19970 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
19980 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
19990 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
199a0 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
199b0 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
199c0 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
199d0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
199e0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
199f0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
19a00 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
19a10 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
19a20 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
19a30 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
19a40 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
19a50 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
19a60 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
19a70 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
19a80 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
19a90 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19aa0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19ab0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19ac0 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
19ad0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
19ae0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
19af0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19b00 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
19b10 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
19b20 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
19b30 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
19b40 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
19b50 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19b60 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
19b70 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
19b80 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19b90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
19ba0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
19bb0 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
19bc0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
19bd0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
19be0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19bf0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
19c00 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
19c10 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
19c20 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
19c30 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
19c40 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
19c50 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
19c60 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
19c70 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
19c80 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19c90 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
19ca0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
19cb0 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65  et the Last Inse
19cc0 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a  rt Rowid value..
19cd0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19ce0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
19cf0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
19d00 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29  sert_rowid(D, R)
19d10 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74   method allows t
19d20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
19d30 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c  o.** set the val
19d40 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63  ue returned by c
19d50 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c  alling sqlite3_l
19d60 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19d70 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74  (D) to R .** wit
19d80 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61  hout inserting a
19d90 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61   row into the da
19da0 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20  tabase..*/.void 
19db0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
19dc0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
19dd0 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69  lite3*,sqlite3_i
19de0 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
19df0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
19e00 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
19e10 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
19e20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
19e30 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
19e40 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
19e50 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
19e60 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
19e70 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
19e80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
19e90 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
19ea0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
19eb0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
19ec0 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
19ed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
19ee0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
19ef0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
19f00 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
19f10 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
19f20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
19f30 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
19f40 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
19f50 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
19f60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
19f70 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
19f80 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
19f90 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19fa0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
19fb0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
19fc0 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
19fd0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
19fe0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
19ff0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
1a000 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
1a010 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
1a020 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
1a030 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
1a040 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
1a050 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
1a060 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1a070 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
1a080 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
1a090 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
1a0a0 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
1a0b0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
1a0c0 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
1a0d0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1a0e0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
1a0f0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
1a100 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1a110 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
1a120 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
1a130 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
1a140 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
1a150 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
1a160 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
1a170 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
1a180 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
1a190 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
1a1a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a1b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
1a1c0 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
1a1d0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1a1e0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
1a1f0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
1a200 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
1a210 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
1a220 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1a230 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
1a240 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
1a250 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
1a260 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a270 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
1a280 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
1a290 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
1a2a0 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
1a2b0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1a2c0 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
1a2d0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1a2e0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
1a2f0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1a300 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
1a310 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
1a320 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
1a330 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
1a340 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
1a350 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
1a360 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
1a370 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
1a380 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
1a390 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
1a3a0 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
1a3b0 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
1a3c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a3d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1a3e0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1a3f0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
1a400 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
1a410 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
1a420 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
1a430 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
1a440 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
1a450 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
1a460 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
1a470 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1a480 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
1a490 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
1a4a0 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
1a4b0 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
1a4c0 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
1a4d0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
1a4e0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1a4f0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
1a500 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
1a510 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
1a520 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
1a530 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1a540 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1a550 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1a560 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
1a570 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
1a580 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
1a590 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
1a5a0 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
1a5b0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
1a5c0 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
1a5d0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
1a5e0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
1a5f0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1a600 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
1a610 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a620 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
1a630 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1a640 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1a650 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
1a660 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1a670 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1a680 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
1a690 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
1a6a0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1a6b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1a6c0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1a6d0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1a6e0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1a6f0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1a700 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1a710 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1a720 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1a730 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1a740 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1a750 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1a760 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1a770 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1a780 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1a790 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1a7a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1a7b0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1a7c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
1a7d0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1a7e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a7f0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
1a800 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1a810 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a820 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1a830 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1a840 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
1a850 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
1a860 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
1a870 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
1a880 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
1a890 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1a8a0 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
1a8b0 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
1a8c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a8d0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
1a8e0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
1a8f0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
1a900 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
1a910 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
1a920 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1a930 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1a940 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
1a950 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
1a960 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1a970 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1a980 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
1a990 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
1a9a0 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
1a9b0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
1a9c0 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
1a9d0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
1a9e0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
1a9f0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
1aa00 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1aa10 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
1aa20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
1aa30 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1aa40 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
1aa50 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
1aa60 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
1aa70 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
1aa80 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1aa90 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1aaa0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1aab0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1aac0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
1aad0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
1aae0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1aaf0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1ab00 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1ab10 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1ab20 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1ab30 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1ab40 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1ab50 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1ab60 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1ab70 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1ab80 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1ab90 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1aba0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
1abb0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1abc0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1abd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1abe0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
1abf0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20  unning Query.** 
1ac00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1ac10 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1ac20 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
1ac30 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
1ac40 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
1ac50 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
1ac60 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
1ac70 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
1ac80 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
1ac90 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
1aca0 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
1acb0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
1acc0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
1acd0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
1ace0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
1acf0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
1ad00 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
1ad10 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
1ad20 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
1ad30 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
1ad40 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1ad50 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
1ad60 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
1ad70 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
1ad80 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
1ad90 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
1ada0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
1adb0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
1adc0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1add0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1ade0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1adf0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
1ae00 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
1ae10 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
1ae20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ae30 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
1ae40 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
1ae50 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
1ae60 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
1ae70 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
1ae80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
1ae90 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
1aea0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
1aeb0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
1aec0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
1aed0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
1aee0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
1aef0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
1af00 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
1af10 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
1af20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
1af30 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1af40 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
1af50 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
1af60 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
1af70 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
1af80 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1af90 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
1afa0 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
1afb0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
1afc0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
1afd0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
1afe0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
1aff0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
1b000 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b010 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
1b020 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
1b030 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
1b040 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
1b050 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
1b060 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b070 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
1b080 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
1b090 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1b0a0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1b0b0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1b0c0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1b0d0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
1b0e0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
1b0f0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
1b100 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
1b110 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
1b120 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
1b130 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
1b140 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1b150 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
1b160 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1b170 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1b180 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
1b190 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1b1a0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
1b1b0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
1b1c0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
1b1d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b1e0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
1b1f0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
1b200 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
1b210 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
1b220 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
1b230 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1b240 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
1b250 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
1b260 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1b270 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1b280 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1b290 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1b2a0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f  call returns..*/
1b2b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
1b2c0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
1b2d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b2e0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
1b2f0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1b300 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
1b310 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1b320 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
1b330 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
1b340 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
1b350 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
1b360 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
1b370 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
1b380 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
1b390 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
1b3a0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
1b3b0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
1b3c0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
1b3d0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
1b3e0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
1b3f0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
1b400 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
1b410 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
1b420 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
1b430 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
1b440 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
1b450 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
1b460 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
1b470 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
1b480 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
1b490 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
1b4a0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
1b4b0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
1b4c0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
1b4d0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
1b4e0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
1b4f0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
1b500 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
1b510 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
1b520 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
1b530 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
1b540 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
1b550 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
1b560 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
1b570 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
1b580 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
1b590 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
1b5a0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
1b5b0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
1b5c0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
1b5d0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
1b5e0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
1b5f0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
1b600 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
1b610 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1b620 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
1b630 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
1b640 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
1b650 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
1b660 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
1b670 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
1b680 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
1b690 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1b6a0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
1b6b0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
1b6c0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
1b6d0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
1b6e0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
1b6f0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
1b700 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
1b710 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
1b720 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
1b730 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1b740 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
1b750 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
1b760 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
1b770 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
1b780 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
1b790 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
1b7a0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
1b7b0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
1b7c0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
1b7d0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
1b7e0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
1b7f0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
1b800 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1b810 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
1b820 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
1b830 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1b840 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
1b850 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
1b860 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1b870 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1b880 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
1b890 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1b8a0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
1b8b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1b8c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1b8d0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
1b8e0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1b8f0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
1b900 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
1b910 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
1b920 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1b930 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
1b940 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
1b950 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
1b960 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
1b970 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b980 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
1b990 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
1b9a0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
1b9b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62  .** KEYWORDS: {b
1b9c0 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
1b9d0 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64  back} {busy hand
1b9e0 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
1b9f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1ba00 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1ba10 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72  handler(D,X,P) r
1ba20 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
1ba30 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1ba40 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20  X.** that might 
1ba50 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1ba60 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
1ba70 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
1ba80 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  t is made to acc
1ba90 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74  ess a database t
1baa0 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20  able associated 
1bab0 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  with.** [databas
1bac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1bad0 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72  when another thr
1bae0 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
1baf0 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20  s has the table 
1bb00 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73  locked..** The s
1bb10 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1bb20 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  ler() interface 
1bb30 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  is used to imple
1bb40 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ment.** [sqlite3
1bb50 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1bb60 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73   and [PRAGMA bus
1bb70 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a  y_timeout]..**.*
1bb80 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
1bb90 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
1bba0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
1bbb0 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  SY].** is return
1bbc0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
1bbd0 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
1bbe0 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
1bbf0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1bc00 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
1bc10 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
1bc20 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
1bc30 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
1bc40 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
1bc50 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1bc60 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
1bc70 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
1bc80 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
1bc90 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
1bca0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
1bcb0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1bcc0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
1bcd0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
1bce0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
1bcf0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
1bd00 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
1bd10 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
1bd20 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
1bd30 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
1bd40 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c  nvoked previousl
1bd50 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c  y for the same l
1bd60 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
1bd70 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
1bd80 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1bd90 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
1bda0 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
1bdb0 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
1bdc0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1bdd0 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
1bde0 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a  SY] is returned.
1bdf0 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1be00 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
1be10 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1be20 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1be30 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
1be40 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
1be50 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1be60 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ase and the cycl
1be70 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
1be80 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
1be90 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
1bea0 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
1beb0 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
1bec0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
1bed0 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
1bee0 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
1bef0 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
1bf00 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
1bf10 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
1bf20 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
1bf30 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
1bf40 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
1bf50 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
1bf60 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f  LITE_BUSY].** to
1bf70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1bf80 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
1bf90 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73  king the .** bus
1bfa0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
1bfb0 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
1bfc0 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
1bfd0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1bfe0 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
1bff0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
1c000 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
1c010 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
1c020 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
1c030 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1c040 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1c050 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
1c060 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
1c070 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
1c080 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
1c090 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
1c0a0 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
1c0b0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1c0c0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1c0d0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
1c0e0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
1c0f0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
1c100 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1c110 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
1c120 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
1c130 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
1c140 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
1c150 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
1c160 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
1c170 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
1c180 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
1c190 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
1c1a0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
1c1b0 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
1c1c0 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
1c1d0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1c1e0 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
1c1f0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
1c200 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
1c210 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
1c220 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
1c230 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
1c240 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
1c250 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1c260 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1c270 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1c280 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
1c290 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1c2a0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
1c2b0 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
1c2c0 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
1c2d0 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
1c2e0 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
1c2f0 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
1c300 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1c310 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
1c320 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50  or evaluating [P
1c330 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1c340 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67  ut=N] will chang
1c350 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61  e the.** busy ha
1c360 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63  ndler and thus c
1c370 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75  lear any previou
1c380 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e  sly set busy han
1c390 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
1c3a0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
1c3b0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
1c3c0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
1c3d0 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
1c3e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c3f0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1c400 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1c410 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
1c420 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  ,.** the busy ha
1c430 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65  ndler is not ree
1c440 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63  ntrant.  Any suc
1c450 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
1c460 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
1c470 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
1c480 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
1c490 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
1c4a0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c4b0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
1c4c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1c4d0 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
1c4e0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1c4f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1c500 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
1c510 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f  lite3*,int(*)(vo
1c520 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b  id*,int),void*);
1c530 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c540 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1c550 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eout.** METHOD: 
1c560 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1c570 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1c580 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1c590 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1c5a0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1c5b0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1c5c0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1c5d0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1c5e0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1c5f0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1c600 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1c610 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1c620 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1c630 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1c640 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1c650 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1c660 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1c670 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1c680 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1c690 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1c6a0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1c6b0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1c6c0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1c6d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
1c6e0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
1c6f0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1c700 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
1c710 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
1c720 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
1c730 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
1c740 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
1c750 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1c760 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1c770 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
1c780 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1c790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c7a0 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
1c7b0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
1c7c0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
1c7d0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
1c7e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
1c7f0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
1c800 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1c810 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1c820 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
1c830 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
1c840 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
1c850 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
1c860 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
1c870 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1c880 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1c890 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1c8a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1c8b0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1c8c0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1c8d0 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f  Queries.** METHO
1c8e0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1c8f0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1c900 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1c910 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1c920 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1c930 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1c940 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1c950 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1c960 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1c970 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1c980 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1c990 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1c9a0 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1c9b0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1c9c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1c9d0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1c9e0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1c9f0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1ca00 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1ca10 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1ca20 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1ca30 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1ca40 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1ca50 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1ca60 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1ca70 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1ca80 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1ca90 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1caa0 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1cab0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1cac0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1cad0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1cae0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1caf0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1cb00 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1cb10 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1cb20 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1cb30 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1cb40 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1cb50 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1cb60 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1cb70 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1cb80 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1cb90 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1cba0 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1cbb0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1cbc0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1cbd0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1cbe0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1cbf0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1cc00 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1cc10 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1cc20 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1cc30 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1cc40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1cc50 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1cc60 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1cc70 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1cc80 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1cc90 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1cca0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1ccb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1ccc0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1ccd0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1cce0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1ccf0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1cd00 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1cd10 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1cd20 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1cd30 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1cd40 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1cd50 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1cd60 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1cd70 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1cd80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1cd90 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1cda0 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1cdb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1cdc0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1cdd0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1cde0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1cdf0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1ce00 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1ce10 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1ce20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1ce30 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1ce40 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1ce50 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1ce60 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1ce70 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1ce80 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1ce90 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1cea0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ceb0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1cec0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1ced0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1cee0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1cef0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1cf00 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1cf10 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1cf20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1cf30 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1cf40 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1cf50 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1cf60 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1cf70 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1cf80 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1cf90 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1cfa0 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1cfb0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1cfc0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1cfd0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1cfe0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1cff0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1d000 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d010 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1d020 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1d030 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1d040 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d050 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1d060 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1d070 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1d080 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1d090 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1d0a0 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1d0b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d0c0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1d0d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d0e0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1d0f0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1d100 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1d110 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1d120 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1d130 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1d140 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1d150 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1d160 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1d170 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1d180 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1d190 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1d1a0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1d1b0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1d1c0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1d1d0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1d1e0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1d1f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1d200 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1d210 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1d220 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1d230 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1d240 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1d250 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1d260 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1d270 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1d280 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1d290 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1d2a0 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1d2b0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1d2c0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1d2d0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1d2e0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1d2f0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1d300 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1d310 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1d320 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1d330 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1d340 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1d350 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1d360 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1d370 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d380 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1d390 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1d3a0 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1d3b0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1d3c0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1d3d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1d3e0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1d3f0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1d400 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1d410 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1d420 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1d430 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1d440 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1d450 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1d460 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1d470 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1d480 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1d490 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1d4a0 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1d4b0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1d4c0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1d4d0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1d4e0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1d4f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1d500 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1d510 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1d520 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d530 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1d540 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1d550 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1d560 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1d570 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1d580 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1d590 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1d5a0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1d5b0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1d5c0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1d5d0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1d5e0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1d5f0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1d600 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1d610 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1d620 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1d630 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1d640 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1d650 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1d660 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1d670 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1d680 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1d690 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1d6a0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1d6b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1d6c0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1d6d0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1d6e0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1d6f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1d700 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1d710 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1d720 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1d730 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1d740 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1d750 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
1d760 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
1d770 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
1d780 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69  mon K&R formatti
1d790 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70  ng options,.** p
1d7a0 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  lus some additio
1d7b0 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  nal non-standard
1d7c0 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c   formats, detail
1d7d0 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74  ed below..** Not
1d7e0 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74  e that some of t
1d7f0 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20  he more obscure 
1d800 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1d810 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a  ns from recent.*
1d820 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e  * C-library stan
1d830 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65  dards are omitte
1d840 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c  d from this impl
1d850 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ementation..**.*
1d860 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1d870 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1d880 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1d890 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1d8a0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1d8b0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1d8c0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1d8d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1d8e0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1d8f0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1d900 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1d910 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1d920 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1d930 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1d940 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1d950 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1d960 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1d970 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1d980 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1d990 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1d9a0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1d9b0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1d9c0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1d9d0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1d9e0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1d9f0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1da00 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1da10 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1da20 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1da30 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1da40 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1da50 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1da60 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1da70 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1da80 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1da90 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1daa0 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1dab0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1dac0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1dad0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1dae0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1daf0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1db00 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1db10 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1db20 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1db30 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1db40 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1db50 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1db60 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1db70 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1db80 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1db90 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1dba0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1dbb0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1dbc0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1dbd0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1dbe0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1dbf0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1dc00 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1dc10 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1dc20 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1dc30 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1dc40 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1dc50 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1dc60 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1dc70 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1dc80 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1dc90 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1dca0 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1dcb0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1dcc0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1dcd0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1dce0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1dcf0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1dd00 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1dd10 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1dd20 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1dd30 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1dd40 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1dd50 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1dd60 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1dd70 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1dd80 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1dd90 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1dda0 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1ddb0 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1ddc0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1ddd0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1dde0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ddf0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
1de00 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
1de10 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
1de20 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1de30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1de40 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
1de50 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
1de60 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
1de70 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1de80 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1de90 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1dea0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1deb0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1dec0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1ded0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1dee0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1def0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1df00 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77   "%q", "%Q", "%w
1df10 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  " and "%z" optio
1df20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1df30 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1df40 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1df50 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1df60 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1df70 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1df80 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1df90 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1dfa0 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1dfb0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1dfc0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1dfd0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1dfe0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1dff0 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1e000 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1e010 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1e020 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1e030 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1e040 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1e050 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1e060 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1e070 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1e080 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1e090 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1e0a0 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1e0b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e0c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1e0d0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1e0e0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1e0f0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e100 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1e110 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1e120 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1e130 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1e140 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1e150 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1e160 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1e170 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1e180 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1e190 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1e1a0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1e1b0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1e1c0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1e1d0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1e1e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1e1f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1e200 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1e210 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1e220 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1e230 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1e240 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1e250 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1e260 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1e270 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e280 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1e290 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e2a0 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1e2b0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1e2c0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e2d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1e2e0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1e2f0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1e300 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1e310 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1e320 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1e330 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1e340 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1e350 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1e360 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1e370 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1e380 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1e390 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1e3a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1e3b0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1e3c0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1e3d0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1e3e0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1e3f0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1e400 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1e410 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1e420 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1e430 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1e440 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1e450 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1e460 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1e470 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1e480 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1e490 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1e4a0 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1e4b0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1e4c0 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1e4d0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1e4e0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1e4f0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1e500 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1e510 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1e520 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1e530 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1e540 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1e550 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1e560 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1e570 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1e580 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1e590 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e5a0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1e5b0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1e5c0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1e5d0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1e5e0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1e5f0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1e600 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e610 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1e620 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1e630 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1e640 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1e650 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1e660 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1e670 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1e680 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1e690 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74  (The "%w" format
1e6a0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c  ting option is l
1e6b0 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20  ike "%q" except 
1e6c0 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20  that it expects 
1e6d0 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e  to.** be contain
1e6e0 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65  ed within double
1e6f0 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20  -quotes instead 
1e700 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  of single quotes
1e710 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61  , and it.** esca
1e720 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71  pes the double-q
1e730 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69  uote character i
1e740 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69  nstead of the si
1e750 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68  ngle-quote.** ch
1e760 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20  aracter.)^  The 
1e770 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1e780 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64  option is intend
1e790 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e  ed for safely in
1e7a0 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65  serting.** table
1e7b0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   and column name
1e7c0 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75  s into a constru
1e7d0 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  cted SQL stateme
1e7e0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  nt..**.** ^(The 
1e7f0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1e800 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1e810 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1e820 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1e830 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1e840 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1e850 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1e860 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1e870 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1e880 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1e890 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1e8a0 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
1e8b0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1e8c0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1e8d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1e8e0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1e8f0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1e900 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1e910 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1e920 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1e930 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1e940 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1e950 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1e960 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1e970 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1e980 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1e990 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1e9a0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1e9b0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1e9c0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1e9d0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1e9e0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1e9f0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1ea00 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1ea10 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1ea20 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1ea30 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1ea40 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1ea50 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1ea60 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1ea70 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1ea80 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1ea90 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1eaa0 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1eab0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1eac0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1ead0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1eae0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1eaf0 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1eb00 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1eb10 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1eb20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1eb30 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1eb40 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1eb50 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1eb60 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1eb70 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1eb80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1eb90 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1eba0 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1ebb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1ebc0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1ebd0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1ebe0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1ebf0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1ec00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ec10 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29  ite3_malloc64(N)
1ec20 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a   routine works j
1ec30 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69  ust like.** sqli
1ec40 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78  te3_malloc(N) ex
1ec50 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61  cept that N is a
1ec60 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69  n unsigned 64-bi
1ec70 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  t integer instea
1ec80 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64  d.** of a signed
1ec90 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e   32-bit integer.
1eca0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1ecb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
1ecc0 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
1ecd0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1ece0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1ecf0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1ed00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1ed10 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
1ed20 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
1ed30 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
1ed40 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1ed50 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
1ed60 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
1ed70 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1ed80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1ed90 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
1eda0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
1edb0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
1edc0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
1edd0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
1ede0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
1edf0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
1ee00 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
1ee10 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
1ee20 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
1ee30 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
1ee40 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
1ee50 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
1ee60 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
1ee70 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
1ee80 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
1ee90 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
1eea0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1eeb0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
1eec0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
1eed0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
1eee0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
1eef0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
1ef00 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
1ef10 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1ef20 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1ef30 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
1ef40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1ef50 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72  alloc(X,N) inter
1ef60 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1ef70 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1ef80 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1ef90 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20  tion X to be at 
1efa0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a  least N bytes..*
1efb0 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61  * ^If the X para
1efc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1efd0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a  _realloc(X,N).**
1efe0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1eff0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1f000 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1f010 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1f020 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1f030 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20  )..** ^If the N 
1f040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1f050 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f060 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1f070 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1f080 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1f090 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1f0a0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1f0b0 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a  ite3_free(X)..**
1f0c0 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1f0d0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61  c(X,N) returns a
1f0e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1f0f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1f100 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1f110 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1f120 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  r NULL if insuff
1f130 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1f140 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e   available..** ^
1f150 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1f160 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1f170 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1f180 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1f190 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1f1a0 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1f1b0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1f1c0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1f1d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1f1e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f1f0 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69  X,N) and the pri
1f200 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1f210 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If 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 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,N) returns NULL
1f240 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69   and N is positi
1f250 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  ve, then the.** 
1f260 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1f270 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1f280 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f290 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29  3_realloc64(X,N)
1f2a0 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b   interfaces work
1f2b0 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a  s the same as.**
1f2c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f2d0 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61  (X,N) except tha
1f2e0 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20  t N is a 64-bit 
1f2f0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1f300 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1f310 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
1f320 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nteger..**.** ^I
1f330 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20  f X is a memory 
1f340 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69  allocation previ
1f350 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
1f360 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1f370 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1f380 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c  _malloc64(), sql
1f390 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20  ite3_realloc(), 
1f3a0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1f3b0 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20  oc64(), then.** 
1f3c0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1f3d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
1f3e0 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79  e of that memory
1f3f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62   allocation in b
1f400 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61  ytes..** ^The va
1f410 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1f420 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1f430 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
1f440 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72   than the number
1f450 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71  .** of bytes req
1f460 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61  uested when X wa
1f470 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49  s allocated.  ^I
1f480 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f X is a NULL po
1f490 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71  inter then.** sq
1f4a0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1f4b0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66  eturns zero.  If
1f4c0 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d   X points to som
1f4d0 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e  ething that is n
1f4e0 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e  ot.** the beginn
1f4f0 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ing of memory al
1f500 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20  location, or if 
1f510 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66  it points to a f
1f520 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64  ormerly.** valid
1f530 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f540 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20  on that has now 
1f550 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e  been freed, then
1f560 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
1f570 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   of sqlite3_msiz
1f580 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65  e(X) is undefine
1f590 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68  d and possibly h
1f5a0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  armful..**.** ^T
1f5b0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1f5c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1f5d0 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f  lloc(), sqlite3_
1f5e0 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  realloc(),.** sq
1f5f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1f600 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
1f610 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20  alloc64().** is 
1f620 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
1f630 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
1f640 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
1f650 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
1f660 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
1f670 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
1f680 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
1f690 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
1f6a0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
1f6b0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
1f6c0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
1f6d0 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
1f6e0 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
1f6f0 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
1f700 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
1f710 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
1f720 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
1f730 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
1f740 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
1f750 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
1f760 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
1f770 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
1f780 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
1f790 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
1f7a0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1f7b0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
1f7c0 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
1f7d0 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
1f7e0 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
1f7f0 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
1f800 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
1f810 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
1f820 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1f830 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
1f840 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
1f850 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
1f860 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1f870 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
1f880 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
1f890 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
1f8a0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
1f8b0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
1f8c0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
1f8d0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
1f8e0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
1f8f0 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
1f900 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
1f910 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1f920 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1f930 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1f940 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1f950 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1f960 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1f970 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1f980 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1f990 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1f9a0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1f9b0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1f9c0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1f9d0 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1f9e0 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1f9f0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1fa00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1fa10 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1fa20 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1fa30 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1fa40 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
1fa50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
1fa60 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
1fa70 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
1fa80 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
1fa90 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
1faa0 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
1fab0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1fac0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
1fad0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fae0 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
1faf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1fb00 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1fb10 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
1fb20 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a  _uint64);.void *
1fb30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fb40 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
1fb50 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1fb60 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69  oc64(void*, sqli
1fb70 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1fb80 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
1fb90 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75  oid*);.sqlite3_u
1fba0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73  int64 sqlite3_ms
1fbb0 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ize(void*);../*.
1fbc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1fbd0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1fbe0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1fbf0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1fc00 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1fc10 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1fc20 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1fc30 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1fc40 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1fc50 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1fc60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1fc70 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1fc80 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1fc90 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1fca0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1fcb0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1fcc0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1fcd0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1fce0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1fcf0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1fd00 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1fd10 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1fd20 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1fd30 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1fd40 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1fd50 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1fd60 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1fd70 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1fd80 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1fd90 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1fda0 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1fdb0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1fdc0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1fdd0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1fde0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1fdf0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1fe00 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1fe10 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1fe20 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1fe30 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1fe40 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1fe50 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1fe60 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1fe70 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1fe80 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1fe90 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1fea0 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1feb0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1fec0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1fed0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1fee0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1fef0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1ff00 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1ff10 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1ff20 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1ff30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1ff40 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1ff50 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1ff60 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1ff70 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1ff80 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1ff90 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1ffa0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1ffb0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1ffc0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1ffd0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1ffe0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1fff0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
20000 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
20010 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
20020 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
20030 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20040 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
20050 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
20060 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
20070 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
20080 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
20090 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
200a0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
200b0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
200c0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
200d0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
200e0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
200f0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
20100 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
20110 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
20120 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
20130 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
20140 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
20150 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
20160 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
20170 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
20180 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
20190 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
201a0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
201b0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
201c0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
201d0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
201e0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
201f0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
20200 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
20210 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
20220 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
20230 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
20240 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65  uffer P..** ^The
20250 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e   P parameter can
20260 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
20270 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
20280 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e  is routine has n
20290 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  ot been previous
202a0 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20  ly called or if 
202b0 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20  the previous.** 
202c0 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20  call had N less 
202d0 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55  than one or a NU
202e0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50  LL pointer for P
202f0 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20  , then the PRNG 
20300 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69  is.** seeded usi
20310 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
20320 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  tained from the 
20330 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
20340 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66  od of.** the def
20350 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
20360 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49  s] object..** ^I
20370 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
20380 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
20390 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20  ine had an N of 
203a0 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a  1 or more and a.
203b0 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68  ** non-NULL P th
203c0 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  en the pseudo-ra
203d0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
203e0 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
203f0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
20400 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
20410 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
20420 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
20430 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
20440 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
20450 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
20460 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20470 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
20480 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
20490 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
204a0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59  : sqlite3.** KEY
204b0 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a  WORDS: {authoriz
204c0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a  er callback}.**.
204d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
204e0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
204f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20500 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
20510 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
20520 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
20530 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
20540 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
20550 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
20560 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20570 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
20580 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
20590 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
205a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
205b0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
205c0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
205d0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
205e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
205f0 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
20600 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73  prepare16()], [s
20610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20620 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  _v2()],.** and [
20630 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20640 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v3()].  ^At va
20650 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
20660 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
20670 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
20680 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
20690 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
206a0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
206b0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
206c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
206d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
206e0 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
206f0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
20700 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
20710 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
20720 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
20730 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
20740 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
20750 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
20760 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
20770 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
20780 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
20790 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
207a0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
207b0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
207c0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
207d0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
207e0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
207f0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
20800 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
20810 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
20820 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
20830 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
20840 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
20850 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
20860 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
20870 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
20880 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
20890 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
208a0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
208b0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
208c0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
208d0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
208e0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
208f0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
20900 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20910 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
20920 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
20930 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
20940 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
20950 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
20960 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
20970 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
20980 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20990 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
209a0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
209b0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
209c0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
209d0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
209e0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
209f0 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
20a00 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
20a10 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
20a20 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
20a30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20a40 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
20a50 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
20a60 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
20a70 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
20a80 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
20a90 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
20aa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
20ab0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
20ac0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
20ad0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
20ae0 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
20af0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
20b00 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
20b10 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
20b20 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
20b30 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
20b40 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
20b50 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
20b60 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e  either NULL poin
20b70 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72  ters or zero-ter
20b80 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a  minated strings.
20b90 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  ** that contain 
20ba0 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
20bb0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
20bc0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
20bd0 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  ized..** Applica
20be0 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79  tions must alway
20bf0 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f  s be prepared to
20c00 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c   encounter a NUL
20c10 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79  L pointer in any
20c20 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64  .** of the third
20c30 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78   through the six
20c40 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  th parameters of
20c50 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
20c60 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
20c70 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
20c80 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
20c90 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
20ca0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20cb0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
20cc0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
20cd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20ce0 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
20cf0 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
20d00 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
20d10 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
20d20 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
20d30 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
20d40 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
20d50 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
20d60 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
20d70 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
20d80 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
20d90 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
20da0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
20db0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
20dc0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
20dd0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
20de0 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65  a table..** ^Whe
20df0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66  n a table is ref
20e00 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45  erenced by a [SE
20e10 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c  LECT] but no col
20e20 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a  umn values are.*
20e30 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  * extracted from
20e40 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72   that table (for
20e50 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75   example in a qu
20e60 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c  ery like.** "SEL
20e70 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f  ECT count(*) FRO
20e80 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65  M tab") then the
20e90 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
20ea0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20eb0 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  ck.** is invoked
20ec0 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74   once for that t
20ed0 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75  able with a colu
20ee0 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20  mn name that is 
20ef0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
20f00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
20f10 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
20f20 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
20f30 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20f40 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
20f50 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
20f60 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
20f70 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
20f80 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
20f90 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
20fa0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
20fb0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
20fc0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
20fd0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
20fe0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
20ff0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
21000 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
21010 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
21020 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
21030 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
21040 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
21050 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
21060 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
21070 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
21080 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
21090 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
210a0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
210b0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
210c0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
210d0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
210e0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
210f0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
21100 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
21110 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
21120 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
21130 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
21140 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
21150 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
21160 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
21170 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
21180 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
21190 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
211a0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
211b0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
211c0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
211d0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
211e0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
211f0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
21200 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
21210 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
21220 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
21230 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
21240 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
21250 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
21260 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
21270 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
21280 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
21290 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
212a0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
212b0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
212c0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
212d0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
212e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
212f0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
21300 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
21310 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
21320 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
21330 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
21340 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
21350 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
21360 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
21370 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
21380 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
21390 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
213a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
213b0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
213c0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
213d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
213e0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
213f0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
21400 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
21410 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
21420 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
21430 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
21440 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
21450 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
21460 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
21470 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21480 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
21490 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
214a0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
214b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
214c0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
214d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
214e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
214f0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
21500 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
21510 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21520 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
21530 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
21540 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
21550 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
21560 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
21570 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
21580 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
21590 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
215a0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
215b0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
215c0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
215d0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
215e0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
215f0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
21600 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
21610 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
21620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
21630 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
21640 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
21650 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21660 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
21670 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
21680 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21690 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
216a0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
216b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
216c0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
216d0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
216e0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
216f0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
21700 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
21710 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
21720 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
21730 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
21740 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
21750 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
21760 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
21770 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
21780 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
21790 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
217a0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
217b0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
217c0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
217d0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
217e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
217f0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
21800 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
21810 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
21820 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
21830 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
21840 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21850 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
21860 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
21870 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
21880 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
21890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
218a0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
218b0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
218c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
218d0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
218e0 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
218f0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
21900 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
21910 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
21920 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
21930 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
21940 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
21950 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
21960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
21970 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
21980 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
21990 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
219a0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
219b0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
219c0 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
219d0 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
219e0 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
219f0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
21a00 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
21a10 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
21a20 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
21a30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
21a40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21a50 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
21a60 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
21a70 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
21a80 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
21a90 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
21aa0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
21ab0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
21ac0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
21ad0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
21ae0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
21af0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
21b00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
21b10 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21b20 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
21b30 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
21b40 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
21b50 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
21b60 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
21b70 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
21b80 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
21b90 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
21ba0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
21bb0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
21bc0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
21bd0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
21be0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
21bf0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
21c00 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
21c10 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
21c20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
21c30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21c40 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
21c50 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
21c60 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
21c70 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
21c80 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
21c90 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
21ca0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
21cb0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
21cc0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
21cd0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
21ce0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
21cf0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
21d00 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
21d10 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
21d20 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
21d30 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
21d40 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
21d50 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
21d60 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
21d70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21d80 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
21d90 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
21da0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
21db0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
21dc0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
21dd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21de0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21df0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
21e00 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
21e10 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
21e20 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
21e30 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
21e40 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
21e50 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
21e60 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
21e70 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
21e80 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
21e90 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
21ea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21eb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21ec0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
21ed0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
21ee0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
21ef0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21f00 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
21f10 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
21f20 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21f30 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21f40 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21f50 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
21f60 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
21f70 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21f80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21f90 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21fa0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
21fb0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
21fc0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21fd0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21fe0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21ff0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
22000 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22010 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22020 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22030 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22040 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
22050 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22060 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22070 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22080 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22090 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
220a0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
220b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
220c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
220d0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
220e0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
220f0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22100 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22110 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22120 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
22130 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
22140 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22150 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22160 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22170 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
22180 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
22190 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
221a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
221b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
221c0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
221d0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
221e0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
221f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22210 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
22220 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
22230 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22240 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22250 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22260 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
22270 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
22280 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22290 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
222a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
222b0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
222c0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
222d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
222e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
222f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22300 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
22310 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
22320 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
22330 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22350 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
22360 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
22370 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
22380 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
223a0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
223b0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
223c0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
223d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
223e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
223f0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
22400 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
22410 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
22420 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22430 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
22440 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
22450 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
22460 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22470 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22480 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
22490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
224a0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
224b0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
224c0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
224d0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
224e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
224f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22500 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
22510 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22520 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
22530 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
22540 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
22550 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22560 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22570 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
22580 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
22590 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
225a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
225b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
225c0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
225d0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
225e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
225f0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
22600 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22610 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
22620 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
22630 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
22640 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22650 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22660 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
22670 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
22680 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
22690 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
226a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
226b0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
226c0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
226d0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
226e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
226f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22700 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
22710 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
22720 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
22730 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22750 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
22760 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
22770 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22780 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22790 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
227a0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
227b0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
227c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
227d0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
227e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
227f0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
22800 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
22810 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
22820 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
22830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
22840 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
22850 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
22860 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
22870 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
22880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
22890 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
228a0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
228b0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
228c0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
228d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
228e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
228f0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
22900 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
22910 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
22920 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
22930 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
22940 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22950 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
22960 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
22970 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
22980 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
22990 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
229a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
229b0 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65  es are deprecate
229c0 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  d. Use the [sqli
229d0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
229e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73  interface.** ins
229f0 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74  tead of the rout
22a00 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68  ines described h
22a10 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ere..**.** These
22a20 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
22a30 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
22a40 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
22a50 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
22a60 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
22a70 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
22a80 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
22a90 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
22aa0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
22ab0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
22ac0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22ad0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
22ae0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
22af0 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
22b00 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
22b10 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
22b20 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
22b30 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
22b40 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
22b50 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
22b60 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
22b70 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
22b80 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
22b90 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
22ba0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
22bb0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
22bc0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22bd0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
22be0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
22bf0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
22c00 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
22c10 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
22c20 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
22c30 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
22c40 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
22c50 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
22c60 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
22c70 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
22c80 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
22c90 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
22ca0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
22cb0 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
22cc0 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
22cd0 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
22ce0 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
22cf0 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
22d00 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
22d10 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
22d20 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
22d30 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
22d40 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
22d50 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
22d60 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
22d70 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
22d80 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
22d90 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
22da0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
22db0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
22dc0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
22dd0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
22de0 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
22df0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
22e00 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
22e10 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
22e20 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
22e30 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
22e40 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
22e50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
22e60 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
22e70 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
22e80 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
22e90 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
22ea0 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
22eb0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
22ec0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
22ed0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
22ee0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
22ef0 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
22f00 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
22f10 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
22f20 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
22f30 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
22f40 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
22f50 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
22f60 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
22f70 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
22f80 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
22f90 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
22fa0 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  */.SQLITE_DEPREC
22fb0 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
22fc0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
22fd0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61  *,.   void(*xTra
22fe0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
22ff0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
23000 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
23010 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
23020 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
23030 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
23040 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
23050 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
23060 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
23070 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23080 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74   SQL Trace Event
23090 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
230a0 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45  DS: SQLITE_TRACE
230b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
230c0 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20  stants identify 
230d0 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74  classes of event
230e0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f  s that can be mo
230f0 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67  nitored.** using
23100 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
23110 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e  ace_v2()] tracin
23120 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68  g logic.  The th
23130 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
23140 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
23150 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52  e_v2()] is an OR
23160 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
23170 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  of one or more o
23180 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
23190 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e  ng constants.  ^
231a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
231b0 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
231c0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f  callback.** is o
231d0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
231e0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a  ing constants..*
231f0 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67  *.** New tracing
23200 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
23210 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
23220 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
23230 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
23240 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67  ack has four arg
23250 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63  uments: xCallbac
23260 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
23270 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
23280 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74  s one of the int
23290 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20  eger type codes 
232a0 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43  above..** ^The C
232b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
232c0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
232d0 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  xt pointer passe
232e0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
232f0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
23300 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
23310 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50  _v2()]..** The P
23320 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
23330 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
23340 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
23350 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
23360 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
23370 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64  _TRACE_STMT]] <d
23380 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  t>SQLITE_TRACE_S
23390 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TMT</dt>.** <dd>
233a0 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
233b0 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69  _STMT callback i
233c0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
233d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
233e0 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67  ent.** first beg
233f0 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20  ins running and 
23400 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65  possibly at othe
23410 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74  r times during t
23420 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20  he.** execution 
23430 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
23440 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20  statement, such 
23450 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20  as at the start 
23460 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67  of each.** trigg
23470 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e  er subprogram. ^
23480 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
23490 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
234a0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
234b0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65  statement]. ^The
234c0 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   X argument is a
234d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
234e0 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73  ring which.** is
234f0 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20   the unexpanded 
23500 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20  SQL text of the 
23510 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23520 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  nt or an SQL com
23530 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e  ment .** that in
23540 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f  dicates the invo
23550 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67  cation of a trig
23560 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62  ger.  ^The callb
23570 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a  ack can compute.
23580 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74  ** the same text
23590 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
235a0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62   been returned b
235b0 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  y the legacy [sq
235c0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a  lite3_trace()].*
235d0 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75  * interface by u
235e0 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d  sing the X argum
235f0 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e  ent when X begin
23600 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20  s with "--" and 
23610 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c  invoking.** [sql
23620 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
23630 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e  l(P)] otherwise.
23640 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23650 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20  TRACE_PROFILE]] 
23660 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
23670 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a  _PROFILE</dt>.**
23680 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
23690 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
236a0 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20  llback provides 
236b0 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68  approximately th
236c0 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d  e same.** inform
236d0 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76  ation as is prov
236e0 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ided by the [sql
236f0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20  ite3_profile()] 
23700 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  callback..** ^Th
23710 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
23720 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23730 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23740 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
23750 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e   X argument poin
23760 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69  ts to a 64-bit i
23770 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
23780 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66  the estimated of
23790 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
237a0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61  f nanosecond tha
237b0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
237c0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
237d0 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51   run..** ^The SQ
237e0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
237f0 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  LE callback is i
23800 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
23810 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
23820 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  es..**.** [[SQLI
23830 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c  TE_TRACE_ROW]] <
23840 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
23850 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ROW</dt>.** <dd>
23860 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
23870 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73  _ROW callback is
23880 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
23890 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  r a prepared.** 
238a0 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61  statement genera
238b0 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77  tes a single row
238c0 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a   of result.  .**
238d0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
238e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
238f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23900 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
23910 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
23920 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  is unused..**.**
23930 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
23940 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CLOSE]] <dt>SQLI
23950 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f  TE_TRACE_CLOSE</
23960 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
23970 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
23980 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
23990 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74  voked when a dat
239a0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
239b0 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e  ion closes..** ^
239c0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
239d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
239e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
239f0 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a  nection] object.
23a00 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67  ** and the X arg
23a10 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
23a20 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
23a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
23a40 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30  E_STMT       0x0
23a50 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
23a60 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20  _TRACE_PROFILE  
23a70 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53    0x02.#define S
23a80 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
23a90 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66         0x04.#def
23aa0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
23ab0 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38  _CLOSE      0x08
23ac0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23ad0 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b  : SQL Trace Hook
23ae0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
23af0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
23b00 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23b10 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,M,X,P) interfa
23b20 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74  ce registers a t
23b30 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
23b40 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69   function X agai
23b50 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f  nst [database co
23b60 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69  nnection] D, usi
23b70 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b  ng property mask
23b80 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78   M.** and contex
23b90 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49  t pointer P.  ^I
23ba0 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b  f the X callback
23bb0 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69   is.** NULL or i
23bc0 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20  f the M mask is 
23bd0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69  zero, then traci
23be0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  ng is disabled. 
23bf0 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65   The.** M argume
23c00 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
23c10 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63   bitwise OR-ed c
23c20 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
23c30 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53   zero or more [S
23c40 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e  QLITE_TRACE] con
23c50 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45  stants..**.** ^E
23c60 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  ach call to eith
23c70 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  er sqlite3_trace
23c80 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
23c90 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64  ace_v2() overrid
23ca0 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29  es .** (cancels)
23cb0 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73   any prior calls
23cc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63   to sqlite3_trac
23cd0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
23ce0 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  race_v2()..**.**
23cf0 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b   ^The X callback
23d00 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
23d10 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20  ever any of the 
23d20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65  events identifie
23d30 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20  d by .** mask M 
23d40 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74  occur.  ^The int
23d50 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75  eger return valu
23d60 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62  e from the callb
23d70 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ack is currently
23d80 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f  .** ignored, tho
23d90 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61  ugh this may cha
23da0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65  nge in future re
23db0 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63  leases.  Callbac
23dc0 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  k.** implementat
23dd0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75  ions should retu
23de0 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72  rn zero to ensur
23df0 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69  e future compati
23e00 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
23e10 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
23e20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
23e30 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
23e40 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58  callback(T,C,P,X
23e50 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67  )..** ^The T arg
23e60 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
23e70 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  the [SQLITE_TRAC
23e80 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  E].** constants 
23e90 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20  to indicate why 
23ea0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73  the callback was
23eb0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
23ec0 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
23ed0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
23ee0 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  ntext pointer..*
23ef0 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72  * The P and X ar
23f00 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e  guments are poin
23f10 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69  ters whose meani
23f20 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e  ngs depend on T.
23f30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23f40 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e  e3_trace_v2() in
23f50 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
23f60 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74  ded to replace t
23f70 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
23f80 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
23f90 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73  _trace()] and [s
23fa0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
23fb0 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68  ], both of which
23fc0 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74  .** are deprecat
23fd0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
23fe0 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73  e3_trace_v2(.  s
23ff0 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67  qlite3*,.  unsig
24000 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74  ned uMask,.  int
24010 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73  (*xCallback)(uns
24020 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64  igned,void*,void
24030 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  *,void*),.  void
24040 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   *pCtx.);../*.**
24050 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
24060 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
24070 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
24080 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
24090 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
240a0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
240b0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
240c0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
240d0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
240e0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
240f0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
24100 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
24110 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
24120 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
24130 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
24140 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
24150 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
24160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24170 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
24180 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
24190 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
241a0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
241b0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
241c0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
241d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
241e0 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
241f0 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
24200 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
24210 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
24220 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
24230 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
24240 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
24250 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
24260 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
24270 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
24280 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
24290 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
242a0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
242b0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
242c0 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
242d0 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
242e0 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
242f0 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
24300 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
24310 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
24320 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
24330 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
24340 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
24350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24360 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
24370 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
24380 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
24390 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
243a0 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
243b0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
243c0 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
243d0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
243e0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
243f0 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
24400 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
24410 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
24420 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
24430 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
24440 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
24450 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
24460 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
24470 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
24480 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
24490 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
244a0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
244b0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
244c0 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
244d0 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
244e0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
244f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
24500 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
24510 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
24520 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
24530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
24540 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
24550 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
24560 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
24570 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24580 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
24590 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
245a0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
245b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
245c0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
245d0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
245e0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
245f0 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
24600 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
24610 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
24620 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
24630 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
24640 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
24650 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
24660 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
24670 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
24680 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
24690 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
246a0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
246b0 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
246c0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
246d0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
246e0 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
246f0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
24700 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
24710 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
24720 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
24730 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24740 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
24750 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
24760 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
24770 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
24780 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
24790 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
247a0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
247b0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
247c0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
247d0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
247e0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
247f0 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
24800 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
24810 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
24820 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
24830 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
24840 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
24850 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
24860 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
24870 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
24880 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
24890 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
248a0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
248b0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
248c0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
248d0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
248e0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
248f0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
24900 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
24910 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
24920 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
24930 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
24940 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
24950 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
24960 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
24970 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
24980 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
24990 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
249a0 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
249b0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
249c0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
249d0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
249e0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
249f0 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
24a00 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
24a10 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
24a20 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
24a30 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
24a40 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
24a50 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
24a60 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
24a70 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
24a80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
24a90 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
24aa0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
24ab0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
24ac0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
24ad0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
24ae0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
24af0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
24b00 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
24b10 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
24b20 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
24b30 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
24b40 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
24b50 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
24b60 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
24b70 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
24b80 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
24b90 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
24ba0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
24bb0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
24bc0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
24bd0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
24be0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
24bf0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
24c00 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
24c10 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
24c20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
24c30 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
24c40 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
24c50 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
24c60 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
24c70 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
24c80 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
24c90 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
24ca0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
24cb0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
24cc0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
24cd0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
24ce0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
24cf0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
24d00 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
24d10 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
24d20 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
24d30 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
24d40 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
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 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
24d70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
24d80 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
24d90 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
24da0 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
24db0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
24dc0 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
24dd0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
24de0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
24df0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
24e00 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
24e10 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
24e20 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24e30 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
24e40 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
24e50 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
24e60 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
24e70 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
24e80 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
24e90 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
24ea0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
24eb0 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
24ec0 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
24ed0 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
24ee0 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
24ef0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
24f00 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
24f10 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
24f20 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
24f30 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
24f40 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
24f50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
24f60 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
24f70 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
24f80 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
24f90 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
24fa0 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
24fb0 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
24fc0 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
24fd0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
24fe0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
24ff0 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
25000 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
25010 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
25020 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25030 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
25040 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
25050 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
25060 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
25070 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
25080 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
25090 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
250a0 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
250b0 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
250c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
250d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
250e0 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
250f0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
25100 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
25110 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25120 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
25130 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
25140 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
25150 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
25160 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
25170 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
25180 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
25190 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
251a0 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
251b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
251c0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
251d0 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
251e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
251f0 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
25200 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
25210 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
25220 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
25230 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
25240 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
25250 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
25260 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
25270 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
25280 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25290 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
252a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
252b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
252c0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
252d0 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
252e0 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
252f0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
25300 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
25310 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
25320 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
25330 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
25340 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
25350 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
25360 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
25370 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
25380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
25390 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
253a0 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
253b0 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
253c0 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
253d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
253e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
253f0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25400 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
25410 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
25420 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
25430 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
25440 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
25450 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
25460 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
25470 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
25480 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
25490 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
254a0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
254b0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
254c0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
254d0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
254e0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
254f0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
25500 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
25510 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
25520 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
25530 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
25540 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
25550 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
25560 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
25570 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
25580 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
25590 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
255a0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
255b0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
255c0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
255d0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
255e0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
255f0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
25600 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
25610 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
25620 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
25630 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
25640 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
25650 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
25660 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
25670 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
25680 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
25690 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
256a0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
256b0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
256c0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
256d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
256e0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
256f0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
25700 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
25710 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
25720 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
25730 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
25740 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
25750 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
25760 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
25770 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
25780 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25790 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
257a0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
257b0 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
257c0 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
257d0 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
257e0 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
257f0 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
25800 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
25810 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
25820 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
25830 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
25840 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
25850 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
25860 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
25870 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
25880 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
25890 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
258a0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
258b0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
258c0 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
258d0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
258e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
258f0 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
25900 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
25910 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
25920 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
25930 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
25940 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
25950 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
25960 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
25970 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
25980 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
25990 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
259a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
259b0 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
259c0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
259d0 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
259e0 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
259f0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
25a00 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
25a10 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
25a20 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
25a30 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
25a40 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
25a50 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
25a60 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
25a70 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
25a80 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
25a90 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
25aa0 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
25ab0 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
25ac0 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
25ad0 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
25ae0 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
25af0 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
25b00 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
25b10 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
25b20 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
25b30 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
25b40 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
25b50 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
25b60 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
25b70 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
25b80 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
25b90 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
25ba0 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
25bb0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
25bc0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
25bd0 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
25be0 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
25bf0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
25c00 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
25c10 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
25c20 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
25c30 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
25c40 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
25c50 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
25c60 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25c70 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
25c80 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
25c90 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
25ca0 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
25cb0 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
25cc0 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
25cd0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
25ce0 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
25cf0 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
25d00 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
25d10 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
25d20 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  * ^(On windows, 
25d30 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
25d40 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
25d50 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
25d60 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
25d70 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
25d80 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  .)^.**.** [[core
25d90 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
25da0 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
25db0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
25dc0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
25dd0 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
25de0 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
25df0 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
25e00 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
25e10 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
25e20 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
25e30 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
25e40 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69  Lite and its bui
25e50 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e  lt-in [VFSes] in
25e60 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66  terpret the.** f
25e70 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70  ollowing query p
25e80 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
25e90 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
25ea0 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
25eb0 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
25ec0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
25ed0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
25ee0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
25ef0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
25f00 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
25f10 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
25f20 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
25f30 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
25f40 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
25f50 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
25f60 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
25f70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
25f80 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
25f90 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
25fa0 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
25fb0 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
25fc0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
25fd0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
25fe0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
25ff0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
26000 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
26010 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
26020 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
26030 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
26040 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
26050 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
26060 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
26070 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
26080 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
26090 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
260a0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
260b0 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
260c0 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
260d0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
260e0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
260f0 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
26100 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
26110 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
26120 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
26130 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
26140 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
26150 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
26160 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
26170 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
26180 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
26190 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
261a0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
261b0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
261c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
261d0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
261e0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
261f0 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
26200 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
26210 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
26220 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
26230 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
26240 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
26250 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
26260 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
26270 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
26280 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
26290 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
262a0 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
262b0 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
262c0 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
262d0 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
262e0 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
262f0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
26300 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
26310 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
26320 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
26330 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
26340 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
26350 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
26360 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
26370 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
26380 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
26390 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
263a0 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
263b0 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
263c0 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
263d0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
263e0 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
263f0 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
26400 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
26410 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
26420 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
26430 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
26440 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
26450 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
26460 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
26470 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
26480 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
26490 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
264a0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
264b0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
264c0 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
264d0 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
264e0 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
264f0 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
26500 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
26510 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
26520 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
26530 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
26540 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
26550 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
26560 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
26570 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
26580 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
26590 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
265a0 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
265b0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
265c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
265d0 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
265e0 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
265f0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
26600 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
26610 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
26620 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
26630 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
26640 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
26650 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
26660 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
26670 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
26680 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
26690 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
266a0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
266b0 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c  E flag..**.**  <
266c0 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a  li> <b>psow</b>:
266d0 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d   ^The psow param
266e0 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77  eter indicates w
266f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
26700 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73  e.**     [powers
26710 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70  afe overwrite] p
26720 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20  roperty does or 
26730 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74  does not apply t
26740 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f  o the.**     sto
26750 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68  rage media on wh
26760 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ich the database
26770 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a   file resides..*
26780 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f  *.**  <li> <b>no
26790 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e  lock</b>: ^The n
267a0 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20  olock parameter 
267b0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
267c0 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  ry parameter.** 
267d0 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74      which if set
267e0 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c   disables file l
267f0 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61  ocking in rollba
26800 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73  ck journal modes
26810 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69  .  This.**     i
26820 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63  s useful for acc
26830 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73  essing a databas
26840 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65  e on a filesyste
26850 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a  m that does not.
26860 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c  **     support l
26870 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e  ocking.  Caution
26880 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72  :  Database corr
26890 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73  uption might res
268a0 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20  ult if two.**   
268b0 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73    or more proces
268c0 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65  ses write to the
268d0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61   same database a
268e0 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68  nd any one of th
268f0 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65  ose.**     proce
26900 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b  sses uses nolock
26910 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  =1..**.**  <li> 
26920 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e  <b>immutable</b>
26930 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65  : ^The immutable
26940 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
26950 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a  boolean query.**
26960 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74       parameter t
26970 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
26980 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
26990 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f  file is stored o
269a0 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e  n.**     read-on
269b0 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e  ly media.  ^When
269c0 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65   immutable is se
269d0 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  t, SQLite assume
269e0 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  s that the.**   
269f0 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20    database file 
26a00 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
26a10 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f  d, even by a pro
26a20 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72  cess with higher
26a30 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67  .**     privileg
26a40 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61  e, and so the da
26a50 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
26a60 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61   read-only and a
26a70 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20  ll locking.**   
26a80 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74    and change det
26a90 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c  ection is disabl
26aa0 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65  ed.  Caution: Se
26ab0 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61  tting the immuta
26ac0 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65  ble.**     prope
26ad0 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73  rty on a databas
26ae0 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73  e file that does
26af0 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20   in fact change 
26b00 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20  can result.**   
26b10 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71    in incorrect q
26b20 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64  uery results and
26b30 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  /or [SQLITE_CORR
26b40 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20  UPT] errors..** 
26b50 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53      See also: [S
26b60 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
26b70 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20  TABLE]..**      
26b80 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a   .** </ul>.**.**
26b90 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
26ba0 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
26bb0 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
26bc0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
26bd0 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
26be0 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
26bf0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
26c00 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
26c10 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
26c20 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
26c30 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
26c40 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
26c50 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
26c60 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
26c70 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
26c80 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
26c90 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
26ca0 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
26cb0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
26cc0 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
26cd0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
26ce0 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
26cf0 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
26d00 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
26d10 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
26d20 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
26d30 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
26d40 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
26d50 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
26d60 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
26d70 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
26d80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
26d90 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
26da0 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
26db0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
26dc0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
26dd0 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
26de0 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
26df0 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
26e00 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
26e10 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
26e20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26e30 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
26e40 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
26e50 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
26e60 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
26e70 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
26e80 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
26e90 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
26ea0 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
26eb0 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
26ec0 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
26ed0 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
26ee0 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
26ef0 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
26f00 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
26f10 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
26f20 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
26f30 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
26f40 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
26f50 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
26f60 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
26f70 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
26f80 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
26f90 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
26fa0 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
26fb0 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
26fc0 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
26fd0 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
26fe0 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
26ff0 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
27000 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
27010 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
27020 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
27030 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
27040 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
27050 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
27060 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
27070 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
27080 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
27090 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
270a0 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
270b0 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
270c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
270d0 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
270e0 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
270f0 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
27100 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
27110 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
27120 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
27130 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
27140 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64  unix-dotfile <td
27150 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
27160 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
27170 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
27180 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
27190 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22  S "unix-dotfile"
271a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
271b0 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73  t uses dot-files
271c0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73   in place of pos
271d0 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b  ix advisory lock
271e0 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ing..** <tr><td>
271f0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
27200 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
27210 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
27220 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
27230 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
27240 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
27250 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
27260 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
27270 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
27280 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
27290 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
272a0 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
272b0 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
272c0 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
272d0 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
272e0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
272f0 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
27300 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
27310 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
27320 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
27330 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
27340 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
27350 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
27360 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
27370 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
27380 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
27390 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
273a0 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
273b0 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
273c0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
273d0 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
273e0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
273f0 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
27400 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
27410 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
27420 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
27430 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
27440 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
27450 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
27460 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
27470 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
27480 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
27490 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
274a0 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
274b0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
274c0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
274d0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
274e0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
274f0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
27500 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
27510 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
27520 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
27530 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
27540 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
27550 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
27560 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
27570 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
27580 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
27590 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
275a0 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
275b0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
275c0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
275d0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
275e0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
275f0 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
27600 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
27610 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
27620 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
27630 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
27640 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
27650 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27660 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
27670 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
27680 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
27690 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
276a0 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
276b0 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
276c0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
276d0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
276e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
276f0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
27700 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
27710 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
27720 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
27730 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
27740 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
27750 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
27760 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
27770 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
27780 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
27790 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
277a0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
277b0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
277c0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
277d0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
277e0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
277f0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
27800 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
27810 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
27820 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
27830 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
27840 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
27850 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
27860 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
27870 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
27880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27890 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
278a0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
278b0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
278c0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
278d0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
278e0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
278f0 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
27900 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
27910 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
27920 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
27930 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
27940 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
27950 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
27960 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
27970 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
27980 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
27990 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
279a0 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
279b0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
279c0 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
279d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
279e0 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
279f0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
27a00 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
27a10 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
27a20 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
27a30 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
27a40 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
27a50 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
27a60 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
27a70 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
27a80 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
27a90 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
27aa0 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
27ab0 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
27ac0 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
27ad0 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
27ae0 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
27af0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
27b00 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
27b10 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
27b20 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
27b30 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
27b40 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
27b50 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
27b60 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
27b70 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
27b80 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
27b90 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27ba0 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
27bb0 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
27bc0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
27bd0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
27be0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
27bf0 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
27c00 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
27c10 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
27c20 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
27c30 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
27c40 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
27c50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
27c60 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
27c70 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
27c80 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
27c90 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
27ca0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
27cb0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27cc0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
27cd0 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
27ce0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
27cf0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
27d00 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
27d10 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
27d20 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
27d30 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
27d40 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
27d50 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
27d60 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
27d70 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
27d80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
27d90 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
27da0 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
27db0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
27dc0 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
27dd0 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
27de0 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
27df0 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
27e00 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
27e10 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
27e20 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
27e30 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
27e40 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
27e50 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
27e60 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
27e70 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
27e80 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
27e90 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
27ea0 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
27eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27ec0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
27ed0 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
27ee0 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
27ef0 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
27f00 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
27f10 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
27f20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
27f30 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
27f40 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
27f50 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
27f60 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
27f70 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
27f80 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
27f90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
27fa0 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
27fb0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
27fc0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
27fd0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
27fe0 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
27ff0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
28000 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
28010 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
28020 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
28030 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
28040 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
28050 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
28060 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
28070 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
28080 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
28090 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
280a0 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
280b0 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
280c0 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
280d0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
280e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
280f0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
28100 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
28110 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
28120 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e  har *zParam);.in
28130 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
28140 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
28150 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
28160 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
28170 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69   bDefault);.sqli
28180 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
28190 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
281a0 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
281b0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
281c0 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
281d0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
281e0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
281f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
28200 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te3.**.** ^If th
28210 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71  e most recent sq
28220 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
28230 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
28240 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63   .** [database c
28250 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69  onnection] D fai
28260 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71  led, then the sq
28270 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
28280 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
28290 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
282a0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
282b0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  or [extended res
282c0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
282d0 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a  at.** API call..
282e0 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  ** If the most r
282f0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77  ecent API call w
28300 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a  as successful,.*
28310 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
28320 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
28330 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
28340 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
28350 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
28360 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
28370 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
28380 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
28390 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
283a0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
283b0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
283c0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
283d0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
283e0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
283f0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
28400 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
28410 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
28420 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
28430 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
28440 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
28450 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
28460 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
28470 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
28480 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
28490 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
284a0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
284b0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
284c0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
284d0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
284e0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
284f0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
28500 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
28510 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
28520 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
28530 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
28540 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
28550 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
28560 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
28570 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
28580 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
28590 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
285a0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
285b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
285c0 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
285d0 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
285e0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
285f0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
28600 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
28610 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
28620 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
28630 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
28640 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
28650 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
28660 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
28670 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
28680 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
28690 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
286a0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
286b0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
286c0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
286d0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
286e0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
286f0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
28700 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
28710 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
28720 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
28730 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
28740 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
28750 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
28760 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
28770 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
28780 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
28790 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
287a0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
287b0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
287c0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
287d0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
287e0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
287f0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
28800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28810 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
28820 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
28830 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
28840 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
28850 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
28860 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
28870 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
28880 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
28890 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
288a0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
288b0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
288c0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
288d0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
288e0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
288f0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
28900 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
28910 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
28920 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
28930 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
28940 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
28950 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
28960 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
28970 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
28980 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
28990 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
289a0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
289b0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
289c0 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
289d0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
289e0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
289f0 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
28a00 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
28a10 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
28a20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
28a30 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
28a40 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
28a50 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74  lite3_errstr(int
28a60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28a70 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61  EF: Prepared Sta
28a80 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
28a90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
28aa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
28ab0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
28ac0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
28ad0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
28ae0 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
28af0 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
28b00 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a  tatement that.**
28b10 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c   has been compil
28b20 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66  ed into binary f
28b30 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79  orm and is ready
28b40 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
28b50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66  ..**.** Think of
28b60 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
28b70 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74  ent as a separat
28b80 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72  e computer progr
28b90 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67  am.  The.** orig
28ba0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73  inal SQL text is
28bb0 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41   source code.  A
28bc0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28bd0 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69  ent object .** i
28be0 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f  s the compiled o
28bf0 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c  bject code.  All
28c00 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e   SQL must be con
28c10 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a  verted into a.**
28c20 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28c30 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61  ent before it ca
28c40 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  n be run..**.** 
28c50 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f  The life-cycle o
28c60 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
28c70 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
28c80 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20  ually goes like 
28c90 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
28ca0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
28cb0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
28cc0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
28cd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
28ce0 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c  pare_v2()]..** <
28cf0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
28d00 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  to [parameters] 
28d10 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
28d20 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
28d30 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
28d40 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
28d50 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
28d60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
28d70 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
28d80 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
28d90 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
28da0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
28db0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
28dc0 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
28dd0 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
28de0 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
28df0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
28e00 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
28e10 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
28e20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28e30 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74  ]..** </ol>.*/.t
28e40 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
28e50 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
28e60 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
28e70 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
28e80 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54  me Limits.** MET
28e90 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
28ea0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
28eb0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
28ec0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
28ed0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
28ee0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
28ef0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
28f00 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
28f10 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
28f20 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
28f30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
28f40 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
28f50 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
28f60 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
28f70 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
28f80 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
28f90 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
28fa0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
28fb0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
28fc0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
28fd0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
28fe0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
28ff0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
29000 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
29010 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
29020 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
29030 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
29040 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
29050 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
29060 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
29070 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
29080 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
29090 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
290a0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
290b0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
290c0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
290d0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
290e0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
290f0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
29100 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
29110 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
29120 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
29130 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
29140 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
29150 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
29160 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
29170 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
29180 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
29190 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
291a0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
291b0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
291c0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
291d0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
291e0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
291f0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
29200 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
29210 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
29220 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
29230 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
29240 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
29250 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
29260 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
29270 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
29280 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
29290 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
292a0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
292b0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
292c0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
292d0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
292e0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
292f0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
29300 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
29310 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
29320 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
29330 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
29340 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
29350 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
29360 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
29370 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
29380 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
29390 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
293a0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
293b0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
293c0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
293d0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
293e0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
293f0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
29400 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
29410 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
29420 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
29430 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
29440 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
29450 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
29460 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
29470 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
29480 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
29490 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
294a0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
294b0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
294c0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
294d0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
294e0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
294f0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
29500 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
29510 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
29520 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
29530 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
29540 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
29550 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
29560 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
29570 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
29580 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
29590 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
295a0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
295b0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
295c0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
295d0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
295e0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
295f0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
29600 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
29610 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
29620 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
29630 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
29640 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
29650 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
29660 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
29670 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
29680 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
29690 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
296a0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
296b0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
296c0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
296d0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
296e0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
296f0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
29700 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
29710 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
29720 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
29730 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
29740 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
29750 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
29760 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
29770 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
29780 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
29790 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
297a0 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
297b0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
297c0 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
297d0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
297e0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
297f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29800 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
29810 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29820 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
29830 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
29840 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
29850 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
29860 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
29870 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
29880 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
29890 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
298a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
298b0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
298c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
298d0 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
298e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
298f0 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
29900 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29910 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
29920 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29930 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
29940 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
29950 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
29960 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
29970 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
29980 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
29990 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
299a0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
299b0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
299c0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
299d0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
299e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
299f0 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
29a00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
29a10 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
29a20 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29a30 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
29a40 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
29a50 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
29a60 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29a70 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
29a80 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
29a90 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
29aa0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
29ab0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29ac0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29ad0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
29ae0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
29af0 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
29b00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29b10 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
29b20 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
29b30 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
29b40 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29b50 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
29b60 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
29b70 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
29b80 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
29b90 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
29ba0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73  tatement.  If [s
29bb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29bc0 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65  2()] or.** the e
29bd0 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20  quivalent tries 
29be0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63  to allocate spac
29bf0 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20  e for more than 
29c00 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65  this many opcode
29c10 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65  s.** in a single
29c20 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29c30 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e  ent, an SQLITE_N
29c40 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65  OMEM error is re
29c50 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
29c60 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29c70 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
29c80 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29c90 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
29ca0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
29cb0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29cc0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
29cd0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
29ce0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29cf0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
29d00 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
29d10 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
29d20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29d30 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29d40 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
29d50 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
29d60 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
29d70 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
29d80 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
29d90 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
29da0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
29db0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
29dc0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29dd0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
29de0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
29df0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
29e00 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
29e10 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
29e20 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29e30 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
29e40 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
29e50 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
29e60 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
29e70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29e80 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
29e90 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
29ea0 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
29eb0 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
29ec0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29ed0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
29ee0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29ef0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
29f00 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
29f10 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
29f20 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
29f30 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
29f40 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29f50 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
29f60 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e  THREADS]] ^(<dt>
29f70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
29f80 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e  KER_THREADS</dt>
29f90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29fa0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75  mum number of au
29fb0 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74  xiliary worker t
29fc0 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69  hreads that a si
29fd0 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65  ngle.** [prepare
29fe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79  d statement] may
29ff0 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a   start.</dd>)^.*
2a000 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
2a010 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2a020 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
2a030 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
2a040 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a050 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
2a060 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2a070 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a080 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
2a090 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
2a0a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a0b0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
2a0c0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
2a0d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a0e0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2a0f0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
2a100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a110 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
2a120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
2a130 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a140 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2a150 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
2a160 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
2a170 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
2a180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a190 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
2a1a0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
2a1b0 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
2a1c0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
2a1d0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2a1e0 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
2a1f0 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
2a200 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2a210 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
2a220 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
2a230 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
2a240 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20  R_THREADS       
2a250 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41      11../*.** CA
2a260 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 20  PI3REF: Prepare 
2a270 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
2a280 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
2a290 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73  ne various flags
2a2a0 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 73   that can be pas
2a2b0 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65  sed into.** "pre
2a2c0 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65  pFlags" paramete
2a2d0 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  r of the [sqlite
2a2e0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
2a2f0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2a300 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
2a310 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a  interfaces..**.*
2a320 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20  * New flags may 
2a330 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
2a340 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2a350 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  QLite..**.** <dl
2a360 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52  >.** [[SQLITE_PR
2a370 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2a380 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a390 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2a3a0 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  NT</dt>.** <dd>T
2a3b0 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  he SQLITE_PREPAR
2a3c0 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61  E_PERSISTENT fla
2a3d0 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74  g is a hint to t
2a3e0 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  he query planner
2a3f0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65  .** that the pre
2a400 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a410 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64  will be retained
2a420 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65   for a long time
2a430 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79   and.** probably
2a440 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d   reused many tim
2a450 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74  es.)^ ^Without t
2a460 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74  his flag, [sqlit
2a470 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2a480 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2a490 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2a4a0 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68 65   assume that the
2a4b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a4c0 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20  ent will .** be 
2a4d0 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f  used just once o
2a4e0 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20  r at most a few 
2a4f0 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64  times and then d
2a500 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a  estroyed using.*
2a510 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2a520 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c  ize()] relativel
2a530 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72  y soon. The curr
2a540 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
2a550 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68  on acts.** on th
2a560 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64  is hint by avoid
2a570 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b  ing the use of [
2a580 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2a590 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a  ] so as not to.*
2a5a0 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69  * deplete the li
2a5b0 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c  mited store of l
2a5c0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
2a5d0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
2a5e0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61   of.** SQLite ma
2a5f0 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69  y act on this hi
2a600 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a  nt differently..
2a610 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
2a620 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ine SQLITE_PREPA
2a630 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20 20  RE_PERSISTENT   
2a640 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31 0a             0x01.
2a650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a660 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
2a670 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
2a680 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
2a690 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
2a6a0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2a6b0 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
2a6c0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
2a6d0 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
2a6e0 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  te an SQL statem
2a6f0 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ent, it must fir
2a700 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
2a710 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
2a720 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
2a730 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
2a740 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20  utines.  Or, in 
2a750 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
2a760 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2a770 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 20  re constructors 
2a780 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2a790 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
2a7a0 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ect..**.** The p
2a7b0 72 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e 65  referred routine
2a7c0 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c 69   to use is [sqli
2a7d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a7e0 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  ].  The.** [sqli
2a7f0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 69  te3_prepare()] i
2a800 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65 67 61  nterface is lega
2a810 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62 65  cy and should be
2a820 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71   avoided..** [sq
2a830 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2a840 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72 61  ()] has an extra
2a850 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70 74   "prepFlags" opt
2a860 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65 64  ion that is used
2a870 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c 20  .** for special 
2a880 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
2a890 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 55  The use of the U
2a8a0 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73 20  TF-8 interfaces 
2a8b0 69 73 20 70 72 65 66 65 72 72 65 64 2c 20 61 73  is preferred, as
2a8c0 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74 6c   SQLite currentl
2a8d0 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61  y.** does all pa
2a8e0 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46 2d  rsing using UTF-
2a8f0 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69  8.  The UTF-16 i
2a900 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
2a910 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20 63  ovided.** as a c
2a920 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68 65  onvenience.  The
2a930 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63   UTF-16 interfac
2a940 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65  es work by conve
2a950 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70  rting the.** inp
2a960 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54 46  ut text into UTF
2a970 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e  -8, then invokin
2a980 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  g the correspond
2a990 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72 66  ing UTF-8 interf
2a9a0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ace..**.** The f
2a9b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
2a9c0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
2a9d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2a9e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
2a9f0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
2aa00 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2aa10 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2aa20 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2aa30 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2aa40 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
2aa50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2aa60 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
2aa70 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
2aa80 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
2aa90 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
2aaa0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
2aab0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
2aac0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
2aad0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
2aae0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
2aaf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2ab00 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2ab10 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73  e_v2(),.** and s
2ab20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ab30 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  3().** interface
2ab40 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
2ab50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2ab60 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  16(), sqlite3_pr
2ab70 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a  epare16_v2(),.**
2ab80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2ab90 70 61 72 65 31 36 5f 76 33 28 29 20 75 73 65 20  pare16_v3() use 
2aba0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
2abb0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
2abc0 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65  ment is negative
2abd0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
2abe0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
2abf0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2ac00 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
2ac10 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  e is positive, t
2ac20 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a  hen it is the.**
2ac30 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2ac40 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
2ac50 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a    ^If nByte is z
2ac60 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65  ero, then no pre
2ac70 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2ac80 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e  nt is generated.
2ac90 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65  .** If the calle
2aca0 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65  r knows that the
2acb0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
2acc0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
2acd0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72  ed, then.** ther
2ace0 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72  e is a small per
2acf0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
2ad00 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e  ge to passing an
2ad10 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
2ad20 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20   that.** is the 
2ad30 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2ad40 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
2ad50 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
2ad60 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
2ad70 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
2ad80 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
2ad90 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
2ada0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
2adb0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
2adc0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
2add0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
2ade0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
2adf0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
2ae00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
2ae10 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
2ae20 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
2ae30 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
2ae40 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
2ae50 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
2ae60 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
2ae70 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
2ae80 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
2ae90 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
2aea0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
2aeb0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
2aec0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
2aed0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
2aee0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
2aef0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
2af00 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
2af10 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
2af20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
2af30 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
2af40 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
2af50 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
2af60 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
2af70 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
2af80 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
2af90 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
2afa0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
2afb0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
2afc0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
2afd0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2afe0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2aff0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
2b000 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
2b010 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
2b020 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
2b030 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
2b040 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
2b050 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
2b060 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
2b070 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2b080 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
2b090 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
2b0a0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
2b0b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2b0c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c 20  3_prepare_v2(), 
2b0d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b0e0 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  v3(), sqlite3_pr
2b0f0 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a  epare16_v2(),.**
2b100 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2b110 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74 65  pare16_v3() inte
2b120 72 66 61 63 65 73 20 61 72 65 20 72 65 63 6f 6d  rfaces are recom
2b130 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
2b140 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20  ew programs..** 
2b150 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  The older interf
2b160 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70 72  aces (sqlite3_pr
2b170 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
2b180 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 29  te3_prepare16())
2b190 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65 64  .** are retained
2b1a0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
2b1b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
2b1c0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
2b1d0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
2b1e0 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74 65  In the "vX" inte
2b1f0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
2b200 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2b210 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
2b220 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2b230 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
2b240 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
2b250 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
2b260 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
2b270 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
2b280 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
2b290 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
2b2a0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
2b2b0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
2b2c0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2b2d0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
2b2e0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
2b2f0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
2b300 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2b310 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
2b320 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
2b330 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
2b340 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
2b350 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2b360 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
2b370 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
2b380 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
2b390 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
2b3a0 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
2b3b0 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
2b3c0 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
2b3d0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
2b3e0 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
2b3f0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
2b400 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
2b410 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
2b420 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
2b430 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b440 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
2b450 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
2b460 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
2b470 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
2b480 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
2b490 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
2b4a0 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
2b4b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b4c0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
2b4d0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
2b4e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
2b4f0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
2b500 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
2b510 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
2b520 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
2b530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2b540 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
2b550 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
2b560 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
2b570 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
2b580 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
2b590 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
2b5a0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
2b5b0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
2b5c0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2b5d0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
2b5e0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2b5f0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
2b600 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
2b610 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
2b620 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
2b630 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
2b640 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
2b650 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2b660 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2b670 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
2b680 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
2b690 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
2b6a0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
2b6b0 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
2b6c0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
2b6d0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
2b6e0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
2b6f0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
2b700 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
2b710 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
2b720 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
2b730 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
2b740 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
2b750 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
2b760 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
2b770 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
2b780 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
2b790 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
2b7a0 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
2b7b0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2b7c0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2b7d0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
2b7e0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
2b7f0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
2b800 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
2b810 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2b820 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
2b830 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
2b840 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
2b850 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
2b860 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2b870 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
2b880 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 70  * </li>.**.** <p
2b890 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  >^sqlite3_prepar
2b8a0 65 5f 76 33 28 29 20 64 69 66 66 65 72 73 20 66  e_v3() differs f
2b8b0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70  rom sqlite3_prep
2b8c0 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e  are_v2() only in
2b8d0 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65   having.** the e
2b8e0 78 74 72 61 20 70 72 65 70 46 6c 61 67 73 20 70  xtra prepFlags p
2b8f0 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20  arameter, which 
2b900 69 73 20 61 20 62 69 74 20 61 72 72 61 79 20 63  is a bit array c
2b910 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72  onsisting of zer
2b920 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20  o or.** more of 
2b930 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50  the [SQLITE_PREP
2b940 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53  ARE_PERSISTENT|S
2b950 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d  QLITE_PREPARE_*]
2b960 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a   flags.  ^The.**
2b970 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b980 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2b990 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68  works exactly th
2b9a0 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
2b9b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2b9c0 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72  ) with a zero pr
2b9d0 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65  epFlags paramete
2b9e0 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  r..** </ol>.*/.i
2b9f0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2ba00 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
2ba10 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2ba20 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2ba30 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2ba40 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2ba50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2ba60 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2ba70 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2ba80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2ba90 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2baa0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2bab0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2bac0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2bad0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2bae0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2baf0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2bb00 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2bb10 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2bb20 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2bb30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2bb40 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
2bb50 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2bb60 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2bb70 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2bb80 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2bb90 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2bba0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2bbb0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2bbc0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2bbd0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2bbe0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2bbf0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2bc00 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2bc10 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2bc20 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2bc30 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2bc40 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2bc50 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2bc60 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2bc70 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2bc80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 0a  te3_prepare_v3(.
2bc90 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2bca0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2bcb0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2bcc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2bcd0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2bce0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2bcf0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2bd00 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2bd10 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2bd20 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2bd30 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2bd40 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65  unsigned int pre
2bd50 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20  pFlags, /* Zero 
2bd60 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50  or more SQLITE_P
2bd70 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f  REPARE_ flags */
2bd80 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2bd90 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2bda0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2bdb0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2bdc0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2bdd0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2bde0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2bdf0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2be00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2be10 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
2be20 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2be30 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2be40 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2be50 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2be60 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2be70 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2be80 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2be90 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2bea0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2beb0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2bec0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2bed0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2bee0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2bef0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2bf00 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2bf10 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2bf20 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2bf30 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2bf40 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2bf50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2bf60 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2bf70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2bf80 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2bf90 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2bfa0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2bfb0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2bfc0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2bfd0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2bfe0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2bff0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2c000 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2c010 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2c020 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2c030 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2c040 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2c050 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2c060 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2c070 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2c080 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2c090 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2c0a0 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c 69  are16_v3(.  sqli
2c0b0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2c0c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2c0d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c0e0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2c0f0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2c100 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2c110 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2c120 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2c130 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2c140 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2c150 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67  ytes. */.  unsig
2c160 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67  ned int prepFlag
2c170 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f  s, /* Zero or mo
2c180 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  re SQLITE_PREPAR
2c190 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71  E_ flags */.  sq
2c1a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2c1b0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2c1c0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2c1d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2c1e0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2c1f0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2c200 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2c210 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
2c220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
2c230 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
2c240 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t SQL.** METHOD:
2c250 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c260 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c270 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63  _sql(P) interfac
2c280 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2c290 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66  ter to a copy of
2c2a0 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51   the UTF-8.** SQ
2c2b0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
2c2c0 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20  reate [prepared 
2c2d0 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20  statement] P if 
2c2e0 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64  P was.** created
2c2f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
2c300 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2c310 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2c320 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2c330 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
2c340 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2c350 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a  pare16_v3()]..**
2c360 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2c370 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e  panded_sql(P) in
2c380 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2c390 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55  a pointer to a U
2c3a0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63  TF-8.** string c
2c3b0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51  ontaining the SQ
2c3c0 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72  L text of prepar
2c3d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77  ed statement P w
2c3e0 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61  ith.** [bound pa
2c3f0 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64  rameters] expand
2c400 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2c410 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72  example, if a pr
2c420 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c430 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
2c440 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78  g the SQL.** tex
2c450 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  t "SELECT $abc,:
2c460 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61  xyz" and if para
2c470 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f  meter $abc is bo
2c480 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32  und to integer 2
2c490 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d  345.** and param
2c4a0 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62  eter :xyz is unb
2c4b0 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ound, then sqlit
2c4c0 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65  e3_sql() will re
2c4d0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67  turn.** the orig
2c4e0 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45  inal string, "SE
2c4f0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2c500 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61  but sqlite3_expa
2c510 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69  nded_sql().** wi
2c520 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43  ll return "SELEC
2c530 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a  T 2345,NULL".)^.
2c540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c550 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2c560 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2c570 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75  rns NULL if insu
2c580 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a  fficient memory.
2c590 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  ** is available 
2c5a0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
2c5b0 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  lt, or if the re
2c5c0 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65  sult would excee
2c5d0 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78  d the.** the max
2c5e0 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67  imum string leng
2c5f0 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  th determined by
2c600 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d   the [SQLITE_LIM
2c610 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a  IT_LENGTH]..**.*
2c620 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  * ^The [SQLITE_T
2c630 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
2c640 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2c650 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20  tion limits the 
2c660 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64  size of.** bound
2c670 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e   parameter expan
2c680 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51  sions.  ^The [SQ
2c690 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d  LITE_OMIT_TRACE]
2c6a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
2c6b0 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73   option causes s
2c6c0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2c6d0 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20  sql() to always 
2c6e0 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a  return NULL..**.
2c6f0 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2c700 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2c710 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e  e3_sql(P) is man
2c720 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  aged by SQLite a
2c730 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  nd is.** automat
2c740 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65  ically freed whe
2c750 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  n the prepared s
2c760 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61  tatement is fina
2c770 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  lized..** ^The s
2c780 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
2c790 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  y sqlite3_expand
2c7a0 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68  ed_sql(P), on th
2c7b0 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a  e other hand,.**
2c7c0 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
2c7d0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2c7e0 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65  c()] and must be
2c7f0 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70   free by the app
2c800 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70  lication.** by p
2c810 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
2c820 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
2c830 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2c840 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
2c850 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2c860 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78  char *sqlite3_ex
2c870 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74  panded_sql(sqlit
2c880 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2c890 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c8a0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2c8b0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2c8c0 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2c8d0 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
2c8e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c8f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2c900 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
2c910 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c920 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2c930 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
2c940 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
2c950 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
2c960 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
2c970 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
2c980 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2c990 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2c9a0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
2c9b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c9c0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2c9d0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
2c9e0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
2c9f0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2ca00 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
2ca10 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
2ca20 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
2ca30 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
2ca40 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
2ca50 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
2ca60 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
2ca70 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
2ca80 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
2ca90 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
2caa0 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
2cab0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2cac0 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
2cad0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
2cae0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2caf0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
2cb00 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
2cb10 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
2cb20 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2cb30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
2cb40 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
2cb50 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2cb60 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
2cb70 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2cb80 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
2cb90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2cba0 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
2cbb0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
2cbc0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
2cbd0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
2cbe0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
2cbf0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
2cc00 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
2cc10 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
2cc20 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
2cc30 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
2cc40 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2cc50 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
2cc60 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
2cc70 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
2cc80 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
2cc90 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2cca0 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
2ccb0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
2ccc0 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
2ccd0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
2cce0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
2ccf0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
2cd00 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
2cd10 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
2cd20 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
2cd30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2cd40 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2cd50 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
2cd60 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2cd70 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2cd80 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2cd90 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2cda0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2cdb0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2cdc0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2cdd0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2cde0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
2cdf0 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73   disk..** ^The s
2ce00 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2ce10 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65  only() interface
2ce20 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f   returns true fo
2ce30 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a  r [BEGIN] since.
2ce40 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c  ** [BEGIN] merel
2ce50 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20  y sets internal 
2ce60 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b  flags, but the [
2ce70 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45  BEGIN|BEGIN IMME
2ce80 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42  DIATE] and.** [B
2ce90 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55  EGIN|BEGIN EXCLU
2cea0 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64  SIVE] commands d
2ceb0 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61  o touch the data
2cec0 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73  base and so.** s
2ced0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2cee0 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66  only() returns f
2cef0 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63  alse for those c
2cf00 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20  ommands..*/.int 
2cf10 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2cf20 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
2cf30 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2cf40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2cf50 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
2cf60 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
2cf70 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
2cf80 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2cf90 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2cfa0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2cfb0 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
2cfc0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2cfd0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
2cfe0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2cff0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
2d000 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
2d010 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
2d020 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2d030 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74  S)] but has neit
2d040 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  her run to compl
2d050 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a  etion (returned.
2d060 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2d070 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
2d080 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20  tep(S)]) nor.** 
2d090 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
2d0a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d0b0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
2d0c0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
2d0d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
2d0e0 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
2d0f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2d100 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
2d110 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
2d120 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
2d130 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
2d140 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
2d150 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2d160 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
2d170 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2d180 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
2d190 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
2d1a0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
2d1b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
2d1c0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
2d1d0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
2d1e0 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
2d1f0 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
2d200 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
2d210 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
2d220 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
2d230 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
2d240 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
2d250 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
2d260 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
2d270 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
2d280 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
2d290 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
2d2a0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
2d2b0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
2d2c0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
2d2d0 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
2d2e0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2d2f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2d300 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d310 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
2d320 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
2d330 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
2d340 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d350 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
2d360 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d370 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
2d380 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
2d390 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
2d3a0 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
2d3b0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
2d3c0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
2d3d0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
2d3e0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
2d3f0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
2d400 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
2d410 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
2d420 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
2d430 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2d440 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
2d450 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
2d460 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
2d470 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
2d480 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
2d490 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2d4a0 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
2d4b0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
2d4c0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
2d4d0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
2d4e0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
2d4f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d500 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
2d510 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
2d520 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
2d530 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
2d540 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2d550 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
2d560 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
2d570 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
2d580 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
2d590 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
2d5a0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
2d5b0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
2d5c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d5d0 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  alue.  The.** [s
2d5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2d5f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  ()] interface ca
2d600 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e  n be used to con
2d610 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a  struct a new .**
2d620 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2d630 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  e3_value from an
2d640 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2d650 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
2d660 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
2d670 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
2d680 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
2d690 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
2d6a0 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
2d6b0 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
2d6c0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
2d6d0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
2d6e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2d6f0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
2d700 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2d710 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2d720 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2d730 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
2d740 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2d750 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
2d760 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
2d770 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2d780 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
2d790 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2d7a0 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
2d7b0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
2d7c0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
2d7d0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
2d7e0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
2d7f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
2d800 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
2d810 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2d820 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
2d830 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
2d840 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2d850 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2d860 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2d870 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d880 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
2d890 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
2d8a0 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
2d8b0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
2d8c0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
2d8d0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
2d8e0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
2d8f0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
2d900 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
2d910 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2d920 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2d930 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2d940 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2d950 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
2d960 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
2d970 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d980 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2d990 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
2d9a0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
2d9b0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
2d9c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
2d9d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d9e0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2d9f0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
2da00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2da10 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
2da20 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2da30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2da40 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
2da50 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
2da60 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2da70 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
2da80 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2da90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2daa0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
2dab0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2dac0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
2dad0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2dae0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
2daf0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
2db00 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
2db10 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
2db20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2db30 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
2db40 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2db50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c  qlite3_value sql
2db60 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
2db70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
2db80 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2db90 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2dba0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
2dbb0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
2dbc0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
2dbd0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
2dbe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2dbf0 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
2dc00 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
2dc10 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2dc20 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
2dc30 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
2dc40 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2dc50 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2dc60 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
2dc70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2dc80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2dc90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
2dca0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
2dcb0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
2dcc0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
2dcd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2dce0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
2dcf0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2dd00 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2dd10 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
2dd20 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
2dd30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2dd40 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
2dd50 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
2dd60 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
2dd70 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
2dd80 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
2dd90 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2dda0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
2ddb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
2ddc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ddd0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
2dde0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
2ddf0 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
2de00 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
2de10 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
2de20 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
2de30 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
2de40 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
2de50 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
2de60 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
2de70 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
2de80 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2de90 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49  3_stmt.**.** ^(I
2dea0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
2deb0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
2dec0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
2ded0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
2dee0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
2def0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
2df00 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
2df10 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
2df20 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
2df30 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
2df40 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2df50 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
2df60 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
2df70 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
2df80 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
2df90 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
2dfa0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
2dfb0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
2dfc0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
2dfd0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
2dfe0 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
2dff0 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
2e000 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
2e010 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
2e020 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
2e030 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
2e040 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
2e050 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
2e060 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
2e070 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
2e080 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2e090 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
2e0a0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
2e0b0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2e0c0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
2e0d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2e0e0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
2e0f0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
2e100 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
2e110 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
2e120 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
2e130 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e140 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
2e150 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
2e160 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2e170 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2e180 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
2e190 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
2e1a0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
2e1b0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
2e1c0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
2e1d0 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
2e1e0 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
2e1f0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
2e200 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
2e210 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2e220 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
2e230 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
2e240 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
2e250 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
2e260 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
2e270 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
2e280 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
2e290 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
2e2a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e2b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2e2c0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
2e2d0 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
2e2e0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
2e2f0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
2e300 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
2e310 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
2e320 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
2e330 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
2e340 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
2e350 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
2e360 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2e370 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
2e380 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
2e390 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
2e3a0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
2e3b0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
2e3c0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
2e3d0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2e3e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2e3f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2e400 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2e410 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
2e420 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2e430 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
2e440 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
2e450 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
2e460 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
2e470 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
2e480 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
2e490 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2e4a0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
2e4b0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
2e4c0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
2e4d0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
2e4e0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2e4f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2e500 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
2e510 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
2e520 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
2e530 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
2e540 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
2e550 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
2e560 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2e570 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
2e580 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2e590 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2e5a0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2e5b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2e5c0 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
2e5d0 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
2e5e0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
2e5f0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
2e600 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
2e610 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2e620 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
2e630 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2e640 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2e650 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2e660 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
2e670 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
2e680 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2e690 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
2e6a0 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
2e6b0 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
2e6c0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2e6d0 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
2e6e0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2e6f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2e700 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e  nd_text64() then
2e710 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74  .** that paramet
2e720 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
2e730 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
2e740 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
2e750 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
2e760 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
2e770 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
2e780 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
2e790 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
2e7a0 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
2e7b0 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
2e7c0 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
2e7d0 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
2e7e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
2e7f0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
2e800 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
2e810 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
2e820 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
2e830 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
2e840 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
2e850 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
2e860 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
2e870 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2e880 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
2e890 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f  ument to the BLO
2e8a0 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e  B and string bin
2e8b0 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a  ding interfaces.
2e8c0 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ** is a destruct
2e8d0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
2e8e0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2e8f0 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
2e900 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
2e910 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
2e920 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
2e930 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
2e940 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2e950 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
2e960 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
2e970 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73  o bind API fails
2e980 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2e990 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
2e9a0 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
2e9b0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
2e9c0 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
2e9d0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2e9e0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
2e9f0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
2ea00 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
2ea10 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
2ea20 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
2ea30 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2ea40 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
2ea50 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
2ea60 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
2ea70 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
2ea80 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2ea90 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
2eaa0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
2eab0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
2eac0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2ead0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
2eae0 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72  ** ^The sixth ar
2eaf0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2eb00 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2eb10 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a  must be one of.*
2eb20 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  * [SQLITE_UTF8],
2eb30 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
2eb40 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2eb50 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
2eb60 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65  F16LE].** to spe
2eb70 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e  cify the encodin
2eb80 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e  g of the text in
2eb90 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2eba0 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65  eter.  If.** the
2ebb0 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2ebc0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2ebd0 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20  text64() is not 
2ebe0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c  one of the.** al
2ebf0 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f  lowed values sho
2ec00 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20  wn above, or if 
2ec10 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2ec20 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a  g is different.*
2ec30 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64  * from the encod
2ec40 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79  ing specified by
2ec50 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
2ec60 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62  eter, then the b
2ec70 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
2ec80 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2ec90 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2eca0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
2ecb0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
2ecc0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
2ecd0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
2ece0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
2ecf0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
2ed00 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
2ed10 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
2ed20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
2ed30 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
2ed40 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
2ed50 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
2ed60 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
2ed70 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
2ed80 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2ed90 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
2eda0 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
2edb0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
2edc0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2edd0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
2ede0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
2edf0 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
2ee00 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
2ee10 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
2ee20 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
2ee30 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
2ee40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2ee50 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c  ind_pointer(S,I,
2ee60 50 2c 54 29 20 72 6f 75 74 69 6e 65 20 63 61 75  P,T) routine cau
2ee70 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 61 72  ses the I-th par
2ee80 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72  ameter in.** [pr
2ee90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2eea0 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53  ] S to have an S
2eeb0 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c  QL value of NULL
2eec0 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65  , but to also be
2eed0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
2eee0 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ith the pointer 
2eef0 50 20 6f 66 20 74 79 70 65 20 54 2e 0a 2a 2a 20  P of type T..** 
2ef00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2ef10 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74  d_pointer() rout
2ef20 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
2ef30 74 6f 20 70 61 73 73 0a 2a 2a 20 68 6f 73 74 2d  to pass.** host-
2ef40 6c 61 6e 67 75 61 67 65 20 70 6f 69 6e 74 65 72  language pointer
2ef50 73 20 69 6e 74 6f 20 5b 61 70 70 6c 69 63 61 74  s into [applicat
2ef60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2ef70 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 5e  functions]..** ^
2ef80 41 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  A parameter that
2ef90 20 69 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20   is initialized 
2efa0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
2efb0 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 5d 20 61  ind_pointer()] a
2efc0 70 70 65 61 72 73 0a 2a 2a 20 74 6f 20 62 65 20  ppears.** to be 
2efd0 61 6e 20 6f 72 64 69 6e 61 72 79 20 53 51 4c 20  an ordinary SQL 
2efe0 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 65 76  NULL value to ev
2eff0 65 72 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74  erything other t
2f000 68 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  han.** [sqlite3_
2f010 76 61 6c 75 65 5f 70 6f 69 6e 74 65 72 28 29 5d  value_pointer()]
2f020 2e 20 20 54 68 65 20 54 20 70 61 72 61 6d 65 74  .  The T paramet
2f030 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73  er should be a s
2f040 74 61 74 69 63 20 73 74 72 69 6e 67 2c 0a 2a 2a  tatic string,.**
2f050 20 70 72 65 66 65 72 61 62 6c 79 20 61 20 73 74   preferably a st
2f060 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 54  ring literal.  T
2f070 68 65 20 70 72 6f 63 65 64 75 72 65 20 74 68 61  he procedure tha
2f080 74 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 73 71  t invokes .** sq
2f090 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74  lite3_bind_point
2f0a0 65 72 28 53 2c 49 2c 50 2c 54 29 20 63 6f 6e 74  er(S,I,P,T) cont
2f0b0 69 6e 75 65 73 20 74 6f 20 6f 77 6e 20 74 68 65  inues to own the
2f0c0 20 50 20 61 6e 64 20 54 20 70 6f 69 6e 74 65 72   P and T pointer
2f0d0 73 20 61 6e 64 0a 2a 2a 20 6d 75 73 74 20 67 75  s and.** must gu
2f0e0 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 6f  arantee that tho
2f0f0 73 65 20 70 6f 69 6e 74 65 72 73 20 72 65 6d 61  se pointers rema
2f100 69 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  in valid until a
2f110 66 74 65 72 20 74 68 65 20 6c 61 73 74 0a 2a 2a  fter the last.**
2f120 20 61 63 63 65 73 73 20 76 69 61 20 5b 73 71 6c   access via [sql
2f130 69 74 65 33 5f 76 61 6c 75 65 5f 70 6f 69 6e 74  ite3_value_point
2f140 65 72 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  er()].  The sqli
2f150 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
2f160 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73  () routine.** is
2f170 20 70 61 72 74 20 6f 66 20 74 68 65 20 5b 70 6f   part of the [po
2f180 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e  inter passing in
2f190 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66  terface] added f
2f1a0 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30  or SQLite 3.20.0
2f1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2f1c0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2f1d0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2f1e0 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2f1f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2f200 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2f210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f220 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2f230 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2f240 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2f250 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2f260 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2f270 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2f280 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2f290 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2f2a0 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2f2b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2f2c0 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2f2d0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2f2e0 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2f2f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f300 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2f310 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2f320 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2f330 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2f340 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2f350 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2f360 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2f370 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2f380 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2f390 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2f3a0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2f3b0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2f3c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f3d0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2f3e0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2f3f0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2f400 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2f410 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2f420 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2f430 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
2f440 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2f450 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
2f460 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
2f470 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
2f480 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
2f490 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2f4a0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
2f4b0 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
2f4c0 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
2f4d0 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
2f4e0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2f4f0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2f500 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2f510 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2f520 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2f530 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2f540 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2f550 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2f560 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2f570 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2f580 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2f590 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2f5a0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2f5b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2f5c0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2f5d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f5e0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2f5f0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2f600 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2f610 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2f620 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f630 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2f640 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2f650 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
2f660 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2f670 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2f680 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2f690 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2f6a0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2f6b0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2f6c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2f6d0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2f6e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2f6f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2f700 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
2f710 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2f720 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
2f730 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2f740 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
2f750 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
2f760 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
2f770 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
2f780 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
2f790 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2f7a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2f7b0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2f7c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2f7d0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2f7e0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2f7f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2f800 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
2f810 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2f820 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
2f830 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2f840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f850 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
2f860 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
2f870 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71  ncoding);.int sq
2f880 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2f890 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f8a0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
2f8b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2f8c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
2f8d0 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d  nter(sqlite3_stm
2f8e0 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20  t*, int, void*, 
2f8f0 63 6f 6e 73 74 20 63 68 61 72 2a 29 3b 0a 69 6e  const char*);.in
2f900 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2f910 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2f920 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2f930 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  n);.int sqlite3_
2f940 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  bind_zeroblob64(
2f950 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f960 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  nt, sqlite3_uint
2f970 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
2f980 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2f990 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
2f9a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2f9b0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2f9c0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2f9d0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2f9e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2f9f0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2fa00 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2fa10 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2fa20 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2fa30 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2fa40 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2fa50 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2fa60 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2fa70 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2fa80 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2fa90 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2faa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2fab0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2fac0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2fad0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2fae0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2faf0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2fb00 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2fb10 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2fb20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2fb30 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2fb40 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2fb50 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2fb60 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2fb70 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2fb80 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2fb90 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2fba0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2fbb0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2fbc0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2fbd0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2fbe0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2fbf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2fc00 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2fc10 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2fc20 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2fc30 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2fc40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2fc50 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2fc60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2fc70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2fc80 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2fc90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2fca0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2fcb0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2fcc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2fcd0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2fce0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2fcf0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
2fd00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2fd10 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
2fd20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
2fd30 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2fd40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2fd50 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
2fd60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
2fd70 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
2fd80 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2fd90 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2fda0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
2fdb0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
2fdc0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
2fdd0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2fde0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
2fdf0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
2fe00 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2fe10 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
2fe20 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
2fe30 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
2fe40 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
2fe50 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
2fe60 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2fe70 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
2fe80 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
2fe90 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
2fea0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
2feb0 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
2fec0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
2fed0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
2fee0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2fef0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
2ff00 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2ff10 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
2ff20 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
2ff30 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
2ff40 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
2ff50 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
2ff60 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
2ff70 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
2ff80 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2ff90 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
2ffa0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
2ffb0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2ffc0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
2ffd0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
2ffe0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
2fff0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
30000 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
30010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
30020 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20  are16_v2()], or 
30030 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30040 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v3()]..**.** 
30050 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
30060 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
30070 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
30080 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30090 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
300a0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
300b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
300c0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
300d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
300e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
300f0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
30100 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
30110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
30120 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
30130 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
30140 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ame.** METHOD: s
30150 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
30160 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
30170 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
30180 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
30190 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
301a0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
301b0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
301c0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
301d0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
301e0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
301f0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
30200 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
30210 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
30220 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
30230 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
30240 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
30250 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
30260 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
30270 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
30280 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
30290 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
302a0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
302b0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
302c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
302d0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
302e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
302f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
30300 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
30310 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
30320 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
30330 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30340 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
30350 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
30360 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
30370 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
30380 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30390 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
303a0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
303b0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
303c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
303d0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
303e0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
303f0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
30400 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30410 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
30420 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
30430 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
30440 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
30450 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
30460 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
30470 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
30480 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
30490 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
304a0 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
304b0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
304c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
304d0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
304e0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
304f0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
30500 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
30510 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
30520 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
30530 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
30540 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30550 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
30560 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
30570 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
30580 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
30590 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
305a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
305b0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
305c0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74   returns 0, that
305d0 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b   means the .** [
305e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
305f0 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64  nt] returns no d
30600 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
30610 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
30620 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74  * ^However, just
30630 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f   because this ro
30640 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
30650 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20  positive number 
30660 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e  does not.** mean
30670 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72   that one or mor
30680 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77  e rows of data w
30690 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
306a0 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74    ^A SELECT stat
306b0 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ement.** will al
306c0 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69  ways have a posi
306d0 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  tive sqlite3_col
306e0 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20  umn_count() but 
306f0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
30700 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
30710 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
30720 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65   the table conte
30730 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74  nt, it might ret
30740 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a  urn no rows..**.
30750 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
30760 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
30770 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
30780 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
30790 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
307a0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
307b0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
307c0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
307d0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
307e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
307f0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
30800 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
30810 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
30820 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
30830 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
30840 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
30850 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
30860 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
30870 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
30880 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30890 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
308a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
308b0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
308c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
308d0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
308e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
308f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
30900 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
30910 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
30920 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
30930 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30940 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
30950 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
30960 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
30970 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
30980 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
30990 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
309a0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
309b0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
309c0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
309d0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
309e0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
309f0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
30a00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30a10 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
30a20 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
30a30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
30a40 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
30a50 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
30a60 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
30a70 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
30a80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
30a90 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
30aa0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
30ab0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
30ac0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
30ad0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
30ae0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
30af0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
30b00 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
30b10 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
30b20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
30b30 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
30b40 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
30b50 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
30b60 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
30b70 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
30b80 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
30b90 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
30ba0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
30bb0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
30bc0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
30bd0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
30be0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
30bf0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
30c00 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
30c10 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
30c20 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
30c30 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
30c40 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
30c50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
30c60 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
30c70 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
30c80 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
30c90 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
30ca0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
30cb0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
30cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
30cd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30ce0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
30cf0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
30d00 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
30d10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
30d20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30d30 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
30d40 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
30d50 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
30d60 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30d70 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
30d80 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
30d90 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
30da0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
30db0 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
30dc0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
30dd0 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
30de0 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
30df0 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
30e00 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
30e10 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
30e20 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
30e30 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
30e40 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
30e50 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
30e60 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
30e70 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
30e80 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
30e90 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
30ea0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
30eb0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
30ec0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
30ed0 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
30ee0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
30ef0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
30f00 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
30f10 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
30f20 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
30f30 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
30f40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30f50 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
30f60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
30f70 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
30f80 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
30f90 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
30fa0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
30fb0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
30fc0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
30fd0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
30fe0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
30ff0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
31000 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
31010 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
31020 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
31030 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
31040 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
31050 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
31060 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
31070 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
31080 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
31090 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
310a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
310b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
310c0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
310d0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
310e0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
310f0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
31100 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
31110 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
31120 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
31130 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
31140 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
31150 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
31160 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
31170 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
31180 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
31190 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
311a0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
311b0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
311c0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
311d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
311e0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
311f0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
31200 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
31210 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
31220 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
31230 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
31240 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
31250 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
31260 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
31270 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
31280 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
31290 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
312a0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
312b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
312c0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
312d0 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
312e0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
312f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
31300 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
31310 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
31320 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
31330 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
31340 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
31350 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
31360 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
31370 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
31380 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
31390 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
313a0 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
313b0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
313c0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
313d0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
313e0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
313f0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
31400 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
31410 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
31420 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
31430 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
31440 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
31450 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
31460 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
31470 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
31480 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
31490 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
314a0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
314b0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
314c0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
314d0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
314e0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
314f0 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
31500 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
31510 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
31520 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
31530 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
31540 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
31550 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
31560 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
31570 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
31580 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
31590 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
315a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
315b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
315c0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
315d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
315e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
315f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
31600 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
31610 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31620 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
31630 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
31640 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
31650 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
31660 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
31670 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
31680 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
31690 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
316a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
316b0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
316c0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
316d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
316e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
316f0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
31700 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
31710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
31720 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
31730 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
31740 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31750 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31760 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
31770 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
31780 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
31790 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
317a0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
317b0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
317c0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
317d0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
317e0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
317f0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
31800 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
31810 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
31820 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
31830 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
31840 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
31850 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
31860 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
31870 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
31880 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
31890 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
318a0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
318b0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
318c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
318d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
318e0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
318f0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
31900 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
31910 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
31920 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
31930 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
31940 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
31950 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
31960 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
31970 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
31980 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
31990 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
319a0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
319b0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
319c0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
319d0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
319e0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
319f0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
31a00 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
31a10 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
31a20 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
31a30 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
31a40 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
31a50 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
31a60 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
31a70 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
31a80 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
31a90 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
31aa0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
31ab0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
31ac0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
31ad0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
31ae0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
31af0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
31b00 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
31b10 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
31b20 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
31b30 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
31b40 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
31b50 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
31b60 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
31b70 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
31b80 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
31b90 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
31ba0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
31bb0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
31bc0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31bd0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
31be0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
31bf0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31c00 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
31c10 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
31c20 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
31c30 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
31c40 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
31c50 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31c60 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31c70 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
31c80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
31c90 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
31ca0 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b  sing any of.** [
31cb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
31cc0 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
31cd0 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
31ce0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
31cf0 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  6_v2()],.** or [
31d00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
31d10 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v3()] or one o
31d20 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
31d30 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
31d40 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
31d50 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
31d60 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
31d70 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
31d80 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
31d90 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
31da0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
31db0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
31dc0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
31dd0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
31de0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
31df0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
31e00 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
31e10 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
31e20 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
31e30 65 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74  e newer "vX" int
31e40 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69  erfaces.** [sqli
31e50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
31e60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
31e70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
31e80 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
31e90 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
31ea0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
31eb0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
31ec0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
31ed0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
31ee0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
31ef0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
31f00 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
31f10 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e  e.** new "vX" in
31f20 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
31f30 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
31f40 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
31f50 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
31f60 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
31f70 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
31f80 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
31f90 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
31fa0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
31fb0 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
31fc0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
31fd0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
31fe0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
31ff0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
32000 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
32010 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
32020 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
32030 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
32040 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
32050 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
32060 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
32070 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
32080 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
32090 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
320a0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
320b0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
320c0 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
320d0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
320e0 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
320f0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
32100 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
32110 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
32120 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
32130 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
32140 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
32150 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
32160 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
32170 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
32180 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
32190 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
321a0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
321b0 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
321c0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
321d0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
321e0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
321f0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
32200 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
32210 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
32220 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
32230 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
32240 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
32250 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
32260 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
32270 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
32280 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
32290 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
322a0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
322b0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
322c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
322d0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
322e0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
322f0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
32300 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
32310 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
32320 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
32330 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
32340 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
32350 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
32360 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
32370 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
32380 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
32390 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
323a0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
323b0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
323c0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
323d0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
323e0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
323f0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
32400 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
32410 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
32420 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
32430 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
32440 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
32450 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
32460 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
32470 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
32480 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
32490 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
324a0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
324b0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
324c0 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
324d0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
324e0 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
324f0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
32500 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
32510 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
32520 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
32530 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
32540 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
32550 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
32560 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
32570 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
32580 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
32590 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
325a0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
325b0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
325c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
325d0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
325e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
325f0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
32600 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
32610 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
32620 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
32630 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
32640 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
32650 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
32660 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
32670 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
32680 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
32690 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
326a0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
326b0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
326c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
326d0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
326e0 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
326f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
32700 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
32710 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
32720 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
32730 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
32740 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
32750 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
32760 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
32770 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
32780 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32790 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
327a0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
327b0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
327c0 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
327d0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
327e0 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
327f0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
32800 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
32810 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
32820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
32830 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
32840 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
32850 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
32860 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
32870 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
32880 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
32890 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
328a0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
328b0 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
328c0 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
328d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
328e0 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
328f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32900 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
32910 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
32920 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
32930 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
32940 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65  .  But after [ve
32950 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20  rsion 3.6.23.1] 
32960 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e  ([dateof:3.6.23.
32970 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  1],.** sqlite3_s
32980 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
32990 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
329a0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
329b0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
329c0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
329d0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
329e0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
329f0 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
32a00 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
32a10 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
32a20 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
32a30 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
32a40 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
32a50 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
32a60 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
32a70 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
32a80 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
32a90 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
32aa0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
32ab0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
32ac0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
32ad0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
32ae0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
32af0 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
32b00 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
32b10 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
32b20 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
32b30 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
32b40 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
32b50 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
32b60 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
32b70 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
32b80 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
32b90 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
32ba0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
32bb0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
32bc0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
32bd0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
32be0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
32bf0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
32c00 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
32c10 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
32c20 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
32c30 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
32c40 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
32c50 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
32c60 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
32c70 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
32c80 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
32c90 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
32ca0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
32cb0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
32cc0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
32cd0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  ents.** using [s
32ce0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
32cf0 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  3()] or [sqlite3
32d00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
32d10 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  * or [sqlite3_pr
32d20 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
32d30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32d40 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61  e16_v3()] instea
32d50 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
32d60 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
32d70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
32d80 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
32d90 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
32da0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
32db0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
32dc0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
32dd0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
32de0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
32df0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
32e00 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73   "vX" interfaces
32e10 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
32e20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32e30 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
32e40 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
32e50 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
32e60 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
32e70 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
32e80 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
32e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32ea0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
32eb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32ec0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
32ed0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
32ee0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
32ef0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
32f00 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
32f10 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
32f20 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
32f30 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
32f40 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
32f50 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
32f60 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
32f70 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
32f80 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
32f90 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
32fa0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
32fb0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
32fc0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
32fd0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
32fe0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
32ff0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
33000 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
33010 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
33020 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
33030 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
33040 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
33050 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
33060 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
33070 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
33080 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
33090 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
330a0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
330b0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
330c0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
330d0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
330e0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
330f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
33100 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
33110 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
33120 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
33130 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
33140 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
33150 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
33160 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
33170 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
33180 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
33190 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
331a0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
331b0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
331c0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
331d0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
331e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
331f0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
33200 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33210 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
33220 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
33230 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
33240 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
33250 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
33260 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
33270 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
33280 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
33290 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
332a0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
332b0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
332c0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
332d0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
332e0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
332f0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
33300 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
33310 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
33320 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
33330 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
33340 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
33350 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
33360 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
33370 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
33380 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
33390 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
333a0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
333b0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
333c0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
333d0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
333e0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
333f0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
33400 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
33410 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
33420 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
33430 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
33440 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
33450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
33460 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
33470 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
33480 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
33490 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
334a0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
334b0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
334c0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
334d0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
334e0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
334f0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
33500 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
33510 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
33520 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
33530 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
33540 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
33550 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
33560 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
33570 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72  .**.** <b>Summar
33580 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b  y:</b>.** <block
33590 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72  quote><table bor
335a0 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e  der=0 cellpaddin
335b0 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d  g=0 cellspacing=
335c0 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  0>.** <tr><td><b
335d0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
335e0 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  blob</b><td>&rar
335f0 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c  r;<td>BLOB resul
33600 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
33610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
33620 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61  ouble</b><td>&ra
33630 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75  rr;<td>REAL resu
33640 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
33650 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33660 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  int</b><td>&rarr
33670 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45  ;<td>32-bit INTE
33680 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  GER result.** <t
33690 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
336a0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62  _column_int64</b
336b0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36  ><td>&rarr;<td>6
336c0 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65  4-bit INTEGER re
336d0 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
336e0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
336f0 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72  n_text</b><td>&r
33700 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45  arr;<td>UTF-8 TE
33710 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  XT result.** <tr
33720 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
33730 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62  column_text16</b
33740 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55  ><td>&rarr;<td>U
33750 54 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c  TF-16 TEXT resul
33760 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
33770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
33780 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  alue</b><td>&rar
33790 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74  r;<td>The result
337a0 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69   as an .** [sqli
337b0 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74  te3_value|unprot
337c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
337d0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  lue] object..** 
337e0 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74  <tr><td>&nbsp;<t
337f0 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73  d>&nbsp;<td>&nbs
33800 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  p;.** <tr><td><b
33810 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33820 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61  bytes</b><td>&ra
33830 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61  rr;<td>Size of a
33840 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54   BLOB.** or a UT
33850 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20  F-8 TEXT result 
33860 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
33870 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33880 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62  olumn_bytes16&nb
33890 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a  sp;&nbsp;</b>.**
338a0 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70   <td>&rarr;&nbsp
338b0 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20  ;&nbsp;<td>Size 
338c0 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58  of UTF-16.** TEX
338d0 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74  T in bytes.** <t
338e0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
338f0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e  _column_type</b>
33900 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65  <td>&rarr;<td>De
33910 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70  fault.** datatyp
33920 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a  e of the result.
33930 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f  ** </table></blo
33940 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c  ckquote>.**.** <
33950 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a  b>Details:</b>.*
33960 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
33970 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
33980 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
33990 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
339a0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
339b0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
339c0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
339d0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
339e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
339f0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
33a00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33a10 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
33a20 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
33a30 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
33a40 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
33a50 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
33a60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33a70 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
33a80 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
33a90 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
33aa0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
33ab0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
33ac0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
33ad0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
33ae0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
33af0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
33b00 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
33b10 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
33b20 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
33b30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
33b40 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
33b50 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
33b60 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
33b70 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
33b80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
33b90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
33ba0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
33bb0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
33bc0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
33bd0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
33be0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
33bf0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
33c00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
33c10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
33c20 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
33c30 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
33c40 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
33c50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
33c60 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
33c70 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
33c80 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
33c90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
33ca0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33cb0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
33cc0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
33cd0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
33ce0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
33cf0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
33d00 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
33d10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
33d20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
33d30 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
33d40 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
33d50 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
33d60 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
33d70 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
33d80 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
33d90 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
33da0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
33db0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33dc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
33dd0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
33de0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
33df0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
33e00 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
33e10 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
33e20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
33e30 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
33e40 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
33e50 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78  ** The first six
33e60 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c   interfaces (_bl
33e70 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e  ob, _double, _in
33e80 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74  t, _int64, _text
33e90 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a  , and _text16).*
33ea0 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68  * each return th
33eb0 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73  e value of a res
33ec0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20  ult column in a 
33ed0 73 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f  specific data fo
33ee0 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65  rmat.  If.** the
33ef0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
33f00 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20  s not initially 
33f10 69 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64  in the requested
33f20 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61   format (for exa
33f30 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20  mple,.** if the 
33f40 71 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e  query returns an
33f50 20 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65   integer but the
33f60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33f70 74 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65  text() interface
33f80 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65  .** is used to e
33f90 78 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65  xtract the value
33fa0 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61  ) then an automa
33fb0 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73  tic type convers
33fc0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
33fd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
33ff0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
34000 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
34010 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
34020 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
34030 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
34040 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
34050 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
34060 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
34070 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
34080 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
34090 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
340a0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
340b0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
340c0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
340d0 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20  ..** The return 
340e0 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33  value of sqlite3
340f0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63  _column_type() c
34100 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
34110 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66  cide which.** of
34120 20 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69   the first six i
34130 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20  nterface should 
34140 62 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61  be used to extra
34150 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61  ct the column va
34160 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  lue..** The valu
34170 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
34180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
34190 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
341a0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20  ingful if no.** 
341b0 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63  automatic type c
341c0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
341d0 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65  occurred for the
341e0 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69   value in questi
341f0 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61  on.  .** After a
34200 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
34210 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  , the result of 
34220 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
34230 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
34240 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74   is undefined, t
34250 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20  hough harmless. 
34260 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
34270 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
34280 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
34290 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
342a0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
342b0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
342c0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
342d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
342e0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
342f0 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74  a TEXT string, t
34300 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
34310 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
34320 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * or sqlite3_col
34330 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e  umn_bytes16() in
34340 74 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20  terfaces can be 
34350 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e  used to determin
34360 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66  e the size.** of
34370 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
34380 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
34390 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
343a0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
343b0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
343c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
343d0 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
343e0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
343f0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
34400 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
34410 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
34420 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
34430 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
34440 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34450 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
34460 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
34470 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
34480 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
34490 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
344a0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
344b0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
344c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
344d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
344e0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
344f0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
34500 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
34510 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
34520 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
34530 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
34540 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
34550 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
34560 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
34570 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
34580 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
34590 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
345a0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
345b0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
345c0 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
345d0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
345e0 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
345f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
34600 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34610 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
34620 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
34630 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34640 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
34650 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
34660 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
34670 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
34680 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
34690 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
346a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
346b0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
346c0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
346d0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
346e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
346f0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
34700 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
34710 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
34720 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
34730 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
34740 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
34750 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
34760 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
34770 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
34780 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
34790 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
347a0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
347b0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
347c0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
347d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
347e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
347f0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
34800 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
34810 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
34820 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
34830 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
34840 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
34850 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
34860 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
34870 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
34880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34890 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
348a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
348b0 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
348c0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
348d0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
348e0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
348f0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
34900 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
34910 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
34920 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
34930 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34940 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
34950 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
34960 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
34970 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
34980 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
34990 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
349a0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
349b0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
349c0 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
349d0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  ointer..**.** <b
349e0 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54  >Warning:</b> ^T
349f0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
34a00 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
34a10 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
34a20 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
34a30 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34a40 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20  ue] object.  In 
34a50 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  a multithreaded 
34a60 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20  environment,.** 
34a70 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
34a80 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
34a90 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  ect may only be 
34aa0 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68  used safely with
34ab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
34ac0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
34ad0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34ae0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
34af0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
34b00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34b10 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
34b20 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
34b30 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
34b40 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
34b50 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
34b60 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
34b70 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
34b80 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
34b90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
34ba0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
34bb0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34bc0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65  bytes()], the be
34bd0 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68  havior is not th
34be0 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e  readsafe..** Hen
34bf0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
34c00 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69  column_value() i
34c10 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e  nterface.** is n
34c20 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65  ormally only use
34c30 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69  ful within the i
34c40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
34c50 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f   .** [applicatio
34c60 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
34c70 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72  nctions] or [vir
34c80 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f  tual tables], no
34c90 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d  t within.** top-
34ca0 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f  level applicatio
34cb0 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  n code..**.** Th
34cc0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
34cd0 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
34ce0 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61  convert the data
34cf0 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75  type of the resu
34d00 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d  lt..** ^For exam
34d10 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
34d20 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
34d30 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
34d40 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
34d50 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
34d60 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
34d70 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
34d80 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
34d90 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
34da0 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
34db0 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
34dc0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
34dd0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
34de0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
34df0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
34e00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
34e10 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
34e20 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
34e30 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
34e40 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
34e50 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
34e60 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
34e70 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
34e80 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
34e90 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
34ea0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
34eb0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
34ec0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
34ed0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
34ee0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
34ef0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
34f00 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
34f10 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
34f20 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
34f30 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
34f40 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
34f50 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
34f60 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
34f70 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
34f80 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
34f90 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
34fa0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
34fb0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
34fc0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
34fd0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
34fe0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
34ff0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
35000 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
35010 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
35020 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
35030 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
35040 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
35050 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
35060 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  R.** <tr><td>  F
35070 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
35080 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
35090 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
350a0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
350b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
350c0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
350d0 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a   [CAST] to BLOB.
350e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
350f0 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
35100 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
35110 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
35120 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
35130 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
35140 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
35150 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
35160 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
35170 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
35180 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
35190 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
351a0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
351b0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
351c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
351d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
351e0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
351f0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
35200 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
35210 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
35220 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
35230 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
35240 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
35250 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
35260 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
35270 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
35280 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
35290 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
352a0 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
352b0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
352c0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
352d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
352e0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
352f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35300 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
35310 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
35320 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
35330 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
35340 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
35350 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
35360 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
35370 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
35380 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
35390 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
353a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
353b0 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
353c0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
353d0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
353e0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
353f0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
35400 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
35410 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
35420 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
35430 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
35440 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
35450 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
35460 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35470 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
35480 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35490 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
354a0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
354b0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
354c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
354d0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
354e0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
354f0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
35500 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
35510 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
35520 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
35530 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
35540 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
35550 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
35560 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
35570 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
35580 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
35590 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
355a0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
355b0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
355c0 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
355d0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
355e0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
355f0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
35600 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
35610 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
35620 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
35630 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
35640 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
35650 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
35660 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
35670 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
35680 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
35690 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
356a0 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
356b0 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
356c0 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
356d0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
356e0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
356f0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
35700 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
35710 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73  safest policy is
35720 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
35730 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
35740 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
35750 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
35760 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
35770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35780 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
35790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
357a0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
357b0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
357c0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
357d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
357e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
357f0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
35800 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
35810 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
35820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35830 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
35840 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
35850 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
35860 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
35870 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35880 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
35890 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
358a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
358b0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
358c0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
358d0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
358e0 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
358f0 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
35900 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
35910 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
35920 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
35930 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
35940 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
35950 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
35960 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
35970 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
35980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35990 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
359a0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
359b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
359c0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
359d0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
359e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
359f0 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
35a00 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
35a10 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
35a20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
35a30 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
35a40 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
35a50 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
35a60 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
35a70 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
35a80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
35a90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
35aa0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
35ab0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
35ac0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
35ad0 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
35ae0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
35af0 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
35b00 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
35b10 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74  tically.  Do not
35b20 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
35b30 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
35b40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
35b50 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
35b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35b70 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
35b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
35b90 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
35ba0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
35bb0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
35bc0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
35bd0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
35be0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
35bf0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
35c00 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
35c10 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
35c20 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
35c30 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
35c40 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
35c50 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
35c60 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
35c70 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
35c80 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
35c90 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
35ca0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
35cb0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
35cc0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
35cd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
35ce0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
35cf0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
35d00 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
35d10 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
35d20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
35d30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35d40 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
35d50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
35d60 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
35d70 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
35d80 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
35d90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
35da0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
35db0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
35dc0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
35dd0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
35de0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
35df0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35e00 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
35e10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
35e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
35e30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
35e40 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
35e50 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
35e60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
35e70 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
35e80 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
35e90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
35ea0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
35eb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
35ec0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
35ed0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
35ee0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
35ef0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
35f00 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
35f10 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
35f20 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
35f30 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
35f40 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
35f50 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
35f60 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
35f70 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
35f80 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
35f90 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
35fa0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
35fb0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
35fc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
35fd0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
35fe0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
35ff0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
36000 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
36010 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
36020 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
36030 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
36040 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
36050 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
36060 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
36070 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
36080 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
36090 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
360a0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
360b0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
360c0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
360d0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
360e0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
360f0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
36100 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
36110 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
36120 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
36130 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
36140 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
36150 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
36160 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
36170 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
36180 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
36190 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
361a0 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
361b0 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
361c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
361d0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
361e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
361f0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
36200 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
36210 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
36220 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
36230 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
36240 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
36250 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
36260 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
36270 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
36280 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
36290 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
362a0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
362b0 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
362c0 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
362d0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
362e0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
362f0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
36300 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
36310 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
36320 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
36330 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
36340 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
36350 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
36360 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
36370 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
36380 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
36390 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
363a0 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
363b0 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
363c0 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
363d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
363e0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
363f0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
36400 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
36410 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
36420 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
36430 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36440 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
36450 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
36460 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
36470 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
36480 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36490 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
364a0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
364b0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
364c0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
364d0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
364e0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
364f0 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
36500 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
36510 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
36520 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
36530 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
36540 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
36550 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
36560 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
36570 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
36580 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
36590 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
365a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
365b0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
365c0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
365d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
365e0 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
365f0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
36600 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
36610 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
36620 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
36630 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
36640 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
36650 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36660 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
36670 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
36680 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
36690 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
366a0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
366b0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
366c0 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
366d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
366e0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
366f0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
36700 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
36710 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36720 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
36730 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
36740 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
36750 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
36760 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
36770 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
36780 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
36790 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
367a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
367b0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
367c0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
367d0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
367e0 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
367f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
36800 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
36810 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
36820 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
36830 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
36840 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
36850 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
36860 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
36870 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
36880 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
36890 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
368a0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
368b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
368c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
368d0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
368e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
368f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36900 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
36910 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
36920 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
36930 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
36940 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
36950 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
36960 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
36970 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
36980 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
36990 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
369a0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
369b0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
369c0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
369d0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
369e0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
369f0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
36a00 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
36a10 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
36a20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
36a30 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
36a40 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
36a50 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
36a60 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
36a70 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
36a80 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
36a90 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
36aa0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
36ab0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
36ac0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
36ad0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
36ae0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
36af0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
36b00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36b10 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
36b20 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
36b30 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
36b40 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
36b50 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
36b60 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
36b70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
36b80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36b90 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
36ba0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
36bb0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
36bc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36bd0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
36be0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
36bf0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
36c00 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
36c10 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
36c20 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
36c30 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
36c40 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
36c50 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
36c60 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
36c70 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
36c80 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
36c90 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
36ca0 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
36cb0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
36cc0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
36cd0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
36ce0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
36cf0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
36d00 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
36d10 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
36d20 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
36d30 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
36d40 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
36d50 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
36d60 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
36d70 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
36d80 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
36d90 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
36da0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
36db0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
36dc0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
36dd0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
36de0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
36df0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
36e00 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
36e10 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
36e20 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
36e30 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
36e40 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
36e50 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
36e60 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
36e70 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
36e80 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
36e90 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
36ea0 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
36eb0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
36ec0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
36ed0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
36ee0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
36ef0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
36f00 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
36f10 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
36f20 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
36f30 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
36f40 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
36f50 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
36f60 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
36f70 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
36f80 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
36f90 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
36fa0 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
36fb0 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
36fc0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
36fd0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
36fe0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
36ff0 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
37000 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
37010 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
37020 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
37030 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
37040 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37050 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
37060 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
37070 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
37080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37090 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
370a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
370b0 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
370c0 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
370d0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
370e0 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
370f0 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
37100 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
37110 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
37120 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
37130 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
37140 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
37150 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
37160 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
37170 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
37180 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
37190 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
371a0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
371b0 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
371c0 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
371d0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
371e0 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
371f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
37200 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
37210 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
37220 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
37230 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
37240 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
37250 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
37260 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
37270 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
37280 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
37290 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
372a0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
372b0 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
372c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
372d0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
372e0 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
372f0 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
37300 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
37310 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
37320 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
37330 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
37340 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
37350 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
37360 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
37370 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
37380 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
37390 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
373a0 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
373b0 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
373c0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
373d0 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
373e0 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
373f0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
37400 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
37410 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
37420 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
37430 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
37440 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
37450 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
37460 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
37470 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
37480 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
37490 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
374a0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
374b0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
374c0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
374d0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
374e0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
374f0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
37500 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
37510 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
37520 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
37530 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
37540 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
37550 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
37560 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
37570 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
37580 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
37590 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
375a0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
375b0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
375c0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
375d0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
375e0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
375f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
37600 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
37610 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
37620 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
37630 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
37640 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
37650 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
37660 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
37670 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
37680 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
37690 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
376a0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
376b0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
376c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
376d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
376e0 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
376f0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
37700 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
37710 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
37720 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
37730 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
37740 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
37750 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
37760 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
37770 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
37780 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
37790 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
377a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
377b0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
377c0 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
377d0 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
377e0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
377f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
37800 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
37810 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
37820 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
37830 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
37840 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
37850 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
37860 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
37870 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
37880 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
37890 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
378a0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
378b0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
378c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
378d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
378e0 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
378f0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
37900 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
37910 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
37920 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
37930 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
37940 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
37950 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
37960 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
37970 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
37980 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
37990 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
379a0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
379b0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
379c0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
379d0 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
379e0 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
379f0 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
37a00 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
37a10 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
37a20 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
37a30 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
37a40 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
37a50 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
37a60 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
37a70 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
37a80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
37a90 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
37aa0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
37ab0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
37ac0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
37ad0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
37ae0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
37af0 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
37b00 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
37b10 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
37b20 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
37b30 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
37b40 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
37b50 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
37b60 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
37b70 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
37b80 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
37b90 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
37ba0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
37bb0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
37bc0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
37bd0 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
37be0 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
37bf0 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
37c00 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
37c10 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
37c20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37c30 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
37c40 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
37c50 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37c60 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
37c70 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
37c80 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
37c90 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
37ca0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
37cb0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
37cc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37cd0 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
37ce0 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
37cf0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
37d00 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
37d10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
37d20 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
37d30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37d40 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
37d50 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
37d60 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
37d70 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
37d80 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
37d90 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
37da0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
37db0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
37dc0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
37dd0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
37de0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
37df0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
37e00 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
37e10 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
37e20 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
37e30 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
37e40 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
37e50 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
37e60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
37e70 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
37e80 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
37e90 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
37ea0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
37eb0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
37ec0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
37ed0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
37ee0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
37ef0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
37f00 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
37f10 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
37f20 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
37f30 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
37f40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37f50 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
37f60 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
37f70 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
37f80 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
37f90 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
37fa0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
37fb0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
37fc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37fd0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
37fe0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
37ff0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
38000 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
38010 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
38020 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
38030 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
38040 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
38050 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
38060 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
38070 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
38080 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
38090 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
380a0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
380b0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
380c0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
380d0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
380e0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
380f0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
38100 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f            1    /
38110 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33  * IMP: R-37514-3
38120 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20  5566 */.#define 
38130 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
38140 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d        2    /* IM
38150 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37  P: R-03371-37637
38160 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
38170 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
38180 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    3    /* IMP: R
38190 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a  -51971-34154 */.
381a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
381b0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
381c0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
381d0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
381e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
381f0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
38200 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
38210 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38220 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
38230 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
38240 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
38250 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
38260 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
38270 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
38280 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
38290 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
382a0 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
382b0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
382c0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
382d0 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
382e0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
382f0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
38300 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
38310 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
38320 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
38330 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
38340 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38350 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
38360 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
38370 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
38380 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
38390 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
383a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
383b0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
383c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
383d0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
383e0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
383f0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
38400 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
38410 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
38420 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
38430 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
38440 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
38450 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
38460 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
38470 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
38480 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
38490 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61  ons.  To encoura
384a0 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74  ge programmers t
384b0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65  o avoid.** these
384c0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77   functions, we w
384d0 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20  ill not explain 
384e0 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
384f0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
38500 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
38510 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
38520 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
38530 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
38540 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
38550 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
38560 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
38570 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
38580 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
38590 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
385a0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
385b0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
385c0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
385d0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
385e0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
385f0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
38600 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
38610 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
38620 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
38630 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
38640 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
38650 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
38660 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
38670 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
38680 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
38690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
386a0 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
386b0 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
386c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
386d0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61  Obtaining SQL Va
386e0 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
386f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
38700 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c  .** <b>Summary:<
38710 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  /b>.** <blockquo
38720 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  te><table border
38730 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30  =0 cellpadding=0
38740 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a   cellspacing=0>.
38750 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
38760 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
38770 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
38780 64 3e 42 4c 4f 42 20 76 61 6c 75 65 0a 2a 2a 20  d>BLOB value.** 
38790 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqli