/ Hex Artifact Content
Login

Artifact 5a61ffbc0ade918025951a7abc9640fd870e5afd8e730b48751298d2404de888:


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 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
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 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53 48  ITE_ERROR_SNAPSH
5200: 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  OT          (SQL
5210: 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c 3c  ITE_ERROR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5280: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5460: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5470: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5480: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5490: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54b0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
54c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54d0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
54e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54f0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
5500: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5510: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
5520: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5530: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5540: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5550: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5560: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5570: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5580: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5590: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
55a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55b0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
55c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55d0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
55e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55f0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
5600: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5610: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
5620: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5630: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5640: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5650: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5660: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5670: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5680: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5690: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
56a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56b0: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
56c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
56d0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
56e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56f0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
5700: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5710: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
5720: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5730: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5740: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5750: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5760: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5770: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5780: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5790: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57b0: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
57c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
57d0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
57e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57f0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5800: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5810: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5830: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5840: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5850: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5870: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5890: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
58a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58b0: 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 20  VNODE           
58c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
58d0: 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (27<<8)).#defi
58e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58f0: 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 20  AUTH            
5900: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5910: 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (28<<8)).#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5930: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 20  BEGIN_ATOMIC    
5940: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5950: 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (29<<8)).#defi
5960: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5970: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 20  COMMIT_ATOMIC   
5980: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5990: 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (30<<8)).#defi
59a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
59b0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 20  ROLLBACK_ATOMIC 
59c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
59d0: 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (31<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
59f0: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5a00: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
5a10: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
5a20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a30: 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  D_VTAB          
5a40: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a50: 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65  D |  (2<<8)).#de
5a60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5a70: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a80: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a90: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ab0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5ac0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5ad0: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5af0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5b00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5b10: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5b40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5b50: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5b70: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b80: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b90: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5ba0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5bb0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5bc0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5bd0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5be0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5bf0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 44  QLITE_CANTOPEN_D
5c00: 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 53  IRTYWAL       (S
5c10: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5c20: 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74 20   (5<<8)) /* Not 
5c30: 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Used */.#define 
5c40: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5c50: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5c60: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5c70: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5c80: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5c90: 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 20  SEQUENCE        
5ca0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5cc0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5cd0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ce0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5cf0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5d00: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5d10: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5d20: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5d30: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5d50: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5d60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5d70: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5d90: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5da0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5db0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5dc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5dd0: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e  _READONLY_CANTIN
5de0: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  IT       (SQLITE
5df0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c  _READONLY | (5<<
5e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5e10: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45  TE_READONLY_DIRE
5e20: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49  CTORY      (SQLI
5e30: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36  TE_READONLY | (6
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5e60: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5e70: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5e80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5ea0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5eb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ec0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5ed0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ee0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5ef0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f00: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f20: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5f30: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5f40: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5f70: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5f80: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5f90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5fb0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5fc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5fd0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5fe0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ff0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
6000: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6010: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
6020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6030: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
6040: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6050: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
6060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6070: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
6080: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
6090: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
60a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
60b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
60c0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
60d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
60e0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
60f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6100: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
6110: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6120: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
6130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6140: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
6150: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
6160: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
6170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6180: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
6190: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
61a0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
61c0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
61d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
61e0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
61f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6200: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6220: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
6230: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
6240: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
6250: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
6260: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
6270: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
6280: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
6290: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
62a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
62b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
62c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
62d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
62e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
62f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6300: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6310: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6320: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6330: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
6340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6350: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
6360: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6370: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
6380: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
63c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
63d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6410: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6420: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6440: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
6450: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
6460: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
6470: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6480: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
6490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
64b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
64d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
64f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6500: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6510: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6520: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
6530: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
6560: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6570: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
6580: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6590: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
65b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
65c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
65d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65e0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
65f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6600: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6620: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6630: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
6640: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6660: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
6670: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
6680: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
66b0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
66c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
66d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66e0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
66f0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6700: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6720: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6730: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6740: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6750: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6760: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
6770: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
6780: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6790: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
67b0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
67c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
67d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6800: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6810: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6820: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6830: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6850: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6860: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
6870: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
68a0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
68b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
68c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
68d0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
68e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
68f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6900: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6910: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6920: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6930: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6940: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6950: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6960: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6970: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
6980: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6990: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
69a0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
69b0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
69c0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
69d0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
69e0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
69f0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6a00: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6a10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6a20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6a30: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6a40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a50: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6a60: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6a70: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6a80: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6aa0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6ab0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6ac0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6ad0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6ae0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6af0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6b00: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6b10: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6b20: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6b30: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6b40: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6b50: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6b60: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6b70: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6b80: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6b90: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6ba0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6bb0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6bc0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6bd0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6be0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6bf0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6c00: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6c10: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6c20: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6c30: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6c40: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6c50: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6c60: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6c70: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6c80: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6c90: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6ca0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6cb0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6cc0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6cd0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6ce0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6cf0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6d00: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6d10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6d20: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6d30: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6d40: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6d50: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6d60: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6d70: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6d80: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6d90: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
6da0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6db0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6dc0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6dd0: 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  es that a file c
6de0: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6df0: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6e00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6e10: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6e20: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6e30: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6e40: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6e50: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6e60: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6e70: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6e80: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6e90: 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eges..**.** The 
6ea0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
6eb0: 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  CH_ATOMIC proper
6ec0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ty means that th
6ed0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
6ee0: 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f  filesystem suppo
6ef0: 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70  rts doing multip
6f00: 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  le write operati
6f10: 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77  ons atomically w
6f20: 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69  hen those.** wri
6f30: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
6f40: 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b  e bracketed by [
6f50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
6f60: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
6f70: 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
6f80: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
6f90: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23  MIC_WRITE]..*/.#
6fa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6fb0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6fc0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6fd0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6ff0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
7000: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
7010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7020: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
7030: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7040: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
7050: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
7060: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
7070: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
7080: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7090: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
70a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
70b0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
70c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
70d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
70e0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
70f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7100: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
7110: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
7120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7130: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
7140: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7150: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
7160: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7170: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
7180: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
7190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
71a0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
71b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
71c0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
71d0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
71e0: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
71f0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
7200: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7210: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
7220: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
7230: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7240: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
7250: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
7260: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
7270: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
7280: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
7290: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
72a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
72b0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
72c0: 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30  IC           0x0
72d0: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
72e0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
72f0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
7300: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
7310: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
7320: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7330: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
7340: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
7350: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
7360: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
7370: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
7380: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
7390: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
73a0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
73b0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
73c0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
73d0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
73e0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
73f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7400: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
7410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7420: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
7430: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
7440: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7450: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
7460: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
7470: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
7480: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
7490: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
74a0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
74b0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
74c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
74d0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
74e0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
74f0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7500: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7510: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7520: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
7530: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7540: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
7550: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
7560: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
7570: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
7580: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
7590: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
75a0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
75b0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
75c0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
75d0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
75e0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
75f0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7600: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7610: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7620: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
7630: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
7640: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7650: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7660: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
7670: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
7680: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7690: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
76a0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
76b0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
76c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
76d0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
76e0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
76f0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7700: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7710: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7720: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7730: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
7740: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7750: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7760: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
7770: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
7780: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
7790: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
77a0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
77b0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
77c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
77d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
77e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
77f0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7800: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7810: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7820: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7830: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7840: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7850: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7860: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7870: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7880: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7890: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
78a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
78b0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
78c0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
78d0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
78e0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
78f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7900: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7910: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7920: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7930: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7940: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7950: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7960: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7980: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7990: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
79a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
79b0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
79c0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
79d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
79e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
79f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7a00: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7a10: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7a20: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7a30: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7a40: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7a50: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7a60: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7a70: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7a80: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7a90: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
7aa0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
7ab0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
7ac0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7ad0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7ae0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7af0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7b00: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7b10: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7b20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7b30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7b40: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7b50: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7b60: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7b70: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7b80: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7b90: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7ba0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7bb0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7bc0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7bd0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7be0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7bf0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7c00: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7c10: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7c20: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7c30: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7c40: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7c50: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7c60: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7c70: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7c80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7c90: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7ca0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7cc0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7cd0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7ce0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7cf0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7d00: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7d10: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7d20: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7d30: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7d40: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7d50: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7d60: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7d70: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7d80: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7d90: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7da0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7db0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7dc0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7de0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7df0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7e00: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7e10: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7e20: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7e30: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7e40: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7e50: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7e60: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7e70: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7e80: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7e90: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7ea0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7eb0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7ec0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7ed0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7ee0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7ef0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7f00: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7f10: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7f20: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7f30: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7f40: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7f50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7f60: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7f70: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7f80: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7f90: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7fa0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7fb0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7fc0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7fd0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7fe0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7ff0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
8000: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
8010: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
8020: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
8030: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
8040: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
8050: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
8060: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
8070: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
8080: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
8090: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
80a0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
80b0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
80c0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
80d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
80e0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
80f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8100: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
8110: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8120: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
8130: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8140: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
8150: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8160: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
8170: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
8180: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
8190: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
81a0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
81b0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
81c0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
81d0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
81e0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
81f0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
8200: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
8210: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
8220: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
8230: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
8240: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
8250: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
8260: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
8270: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
8280: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
8290: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
82a0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
82b0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
82c0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
82d0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
82e0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
82f0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
8300: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8310: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
8320: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
8330: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
8340: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8350: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
8360: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
8370: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
8380: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
8390: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
83a0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
83b0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
83c0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
83d0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
83e0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
83f0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
8400: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
8410: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
8420: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
8430: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
8440: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
8450: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
8460: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
8470: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
8480: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
8490: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
84a0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
84b0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
84c0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
84d0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
84e0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
84f0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8500: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8510: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8520: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
8530: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
8540: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
8550: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
8560: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
8570: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
8580: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
8590: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
85a0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
85b0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
85c0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
85d0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
85e0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
85f0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8600: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8610: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8620: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8630: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
8640: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
8650: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
8660: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
8670: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
8680: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
8690: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
86a0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
86b0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
86c0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
86d0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
86e0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
86f0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8700: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8710: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8720: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
8730: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
8740: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
8750: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
8760: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8770: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
8780: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
8790: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
87a0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
87b0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
87c0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
87d0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
87e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8800: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8810: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8830: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8840: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8850: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8870: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
8890: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
88a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
88b0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88d0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
88e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
88f0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8900: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8910: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8920: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8930: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
8940: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8950: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
8960: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
8970: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
8980: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
8990: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
89a0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
89b0: 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  LE].** <li> [SQL
89c0: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
89d0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ATOMIC].** </ul>
89e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
89f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8a00: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8a10: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8a20: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8a30: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8a40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8a50: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8a60: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
8a70: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
8a80: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8a90: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8aa0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8ab0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8ac0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8ad0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8ae0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8b00: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8b10: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8b20: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8b30: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8b40: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8b50: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8b60: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8b70: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8b80: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8b90: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8ba0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8bb0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8bc0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8bd0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8be0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8bf0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8c00: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8c10: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8c20: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8c30: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8c40: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8c50: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8c60: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8c70: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8c80: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8c90: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8ca0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8cb0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8cc0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8cd0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8ce0: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8cf0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8d00: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8d10: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8d20: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8d30: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8d40: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8d50: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8d60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8d70: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8d80: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8d90: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8da0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8db0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8dc0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8dd0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8de0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8df0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8e00: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8e10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8e20: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8e30: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8e40: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8e50: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8e60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8e70: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8e80: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8e90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ea0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8eb0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8ee0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8ef0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8f00: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8f10: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8f20: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8f30: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8f40: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8f50: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8f60: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8f70: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8f90: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8fa0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8fb0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8fc0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8fd0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8fe0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8ff0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
9000: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
9010: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
9020: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
9030: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
9040: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
9050: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
9060: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
9070: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
9080: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
9090: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
90a0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
90b0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
90c0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
90d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
90e0: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
90f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
9100: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
9110: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9120: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9130: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
9140: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
9150: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9160: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
9170: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
9180: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
9190: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
91a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
91b0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
91c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
91d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
91e0: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
91f0: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
9200: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
9210: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
9220: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
9230: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
9240: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
9250: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
9260: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
9270: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
9280: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
9290: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
92a0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
92b0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
92c0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
92d0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
92e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
92f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
9300: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
9310: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9320: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
9330: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
9340: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9350: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
9360: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9370: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
9380: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9390: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
93a0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
93b0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
93c0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
93d0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
93e0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
93f0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
9400: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
9410: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
9420: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
9430: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9440: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
9450: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
9460: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
9470: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
9480: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
9490: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
94a0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
94b0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
94c0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
94d0: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
94e0: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
94f0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
9500: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
9510: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
9520: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
9530: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
9540: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
9550: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9560: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
9570: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
9580: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
9590: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
95a0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
95b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
95c0: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
95d0: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
95e0: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
95f0: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
9600: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
9610: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
9620: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
9630: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
9640: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
9650: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
9660: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
9670: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
9680: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
9690: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
96a0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
96b0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
96c0: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
96d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
96e0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
96f0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
9700: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9710: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
9720: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
9730: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
9740: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
9750: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
9760: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
9770: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
9780: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
9790: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
97a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
97b0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
97c0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
97d0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
97e0: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
97f0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
9800: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
9810: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
9820: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
9830: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
9840: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
9850: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
9860: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
9870: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
9880: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
9890: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
98a0: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
98b0: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
98c0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
98d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
98e0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
98f0: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9900: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9910: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9920: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9930: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
9940: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9950: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9960: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
9970: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
9980: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9990: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
99a0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
99b0: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
99c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
99d0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
99e0: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
99f0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9a00: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9a10: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9a20: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
9a30: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9a40: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
9a50: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
9a60: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65   journal file (e
9a70: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f  ither.** the [ro
9a80: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20  llback journal] 
9a90: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68  or the [write-ah
9aa0: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20  ead log]) for a 
9ab0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9ac0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9ad0: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
9ae0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9af0: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9b00: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9b10: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9b20: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
9b30: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
9b40: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9b50: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
9b60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9b70: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9b80: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9b90: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
9ba0: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
9bb0: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
9bc0: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
9bd0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
9be0: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
9bf0: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
9c00: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
9c10: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
9c20: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
9c30: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9c40: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9c50: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9c60: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9c70: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9c80: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
9c90: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
9ca0: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
9cb0: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
9cc0: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
9cd0: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
9ce0: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
9cf0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9d00: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
9d10: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
9d20: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
9d30: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9d40: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9d50: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9d60: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9d70: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9d80: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9d90: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9da0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
9db0: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
9dc0: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
9dd0: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
9de0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
9df0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9e00: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9e10: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
9e20: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
9e30: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9e40: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9e50: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9e60: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9e70: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9e80: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9e90: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9ea0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9eb0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9ec0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
9ed0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
9ee0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9ef0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
9f00: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
9f10: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9f20: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
9f30: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9f40: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9f50: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9f60: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9f70: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9f80: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9f90: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
9fa0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
9fb0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
9fc0: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
9fd0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9fe0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9ff0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
a000: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
a010: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a020: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
a030: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
a040: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
a050: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
a060: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
a070: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
a080: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
a090: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a0a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
a0b0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
a0c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
a0d0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
a0e0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a0f0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
a100: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
a110: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
a120: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
a130: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
a140: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
a150: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
a160: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
a170: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
a180: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
a190: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
a1a0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
a1b0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
a1c0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
a1d0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
a1e0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
a1f0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
a200: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
a210: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
a220: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
a230: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
a240: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
a250: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
a260: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
a270: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
a280: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
a290: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
a2a0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
a2b0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
a2c0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
a2d0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
a2e0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
a2f0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
a300: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
a310: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
a320: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
a330: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a340: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
a350: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
a360: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
a370: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
a380: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
a390: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
a3a0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
a3b0: 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65  er is the new re
a3c0: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
a3d0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
a3e0: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
a3f0: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
a400: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
a410: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
a420: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
a430: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
a440: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
a450: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
a460: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
a470: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
a480: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
a490: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
a4a0: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
a4b0: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
a4c0: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
a4d0: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
a4e0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
a4f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a500: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
a510: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a520: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
a530: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a540: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a550: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
a560: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
a570: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
a580: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
a590: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
a5a0: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 28 5b 57  te ahead log ([W
a5b0: 41 4c 20 66 69 6c 65 5d 29 20 61 6e 64 20 73 68  AL file]) and sh
a5c0: 61 72 65 64 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66  ared memory.** f
a5d0: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
a5e0: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
a5f0: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
a600: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
a610: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
a620: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
a630: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
a640: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
a650: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a660: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
a670: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
a680: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
a690: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
a6a0: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
a6b0: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
a6c0: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
a6d0: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
a6e0: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
a6f0: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
a700: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
a710: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
a720: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
a730: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
a740: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
a750: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
a760: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
a770: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
a780: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
a790: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
a7a0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a7b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a7c0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a7d0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a7e0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a7f0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a800: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a810: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
a820: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a830: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a840: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
a850: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
a860: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a870: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a880: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a890: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
a8a0: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
a8b0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a8c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a8d0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a8e0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a8f0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a900: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
a910: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a920: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a930: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
a940: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
a950: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
a960: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
a970: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
a980: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
a990: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
a9a0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
a9b0: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
a9c0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a9d0: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
a9e0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a9f0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
aa00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
aa10: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
aa20: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
aa30: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
aa40: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
aa50: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
aa60: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
aa70: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
aa80: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
aa90: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
aaa0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
aab0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
aac0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
aad0: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
aae0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
aaf0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
ab10: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
ab20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ab30: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
ab40: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
ab50: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
ab60: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
ab70: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
ab80: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
ab90: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
aba0: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
abb0: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
abc0: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
abd0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
abe0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
abf0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
ac00: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
ac10: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
ac20: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
ac30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ac40: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
ac50: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ac60: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
ac70: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
ac80: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
ac90: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
aca0: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
acb0: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
acc0: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
acd0: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
ace0: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
acf0: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
ad00: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
ad10: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
ad20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
ad30: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
ad40: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
ad50: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
ad60: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
ad70: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
ad80: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
ad90: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
ada0: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
adb0: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
adc0: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
add0: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
ade0: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
adf0: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
ae00: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
ae10: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
ae20: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
ae30: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
ae40: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
ae50: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
ae60: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
ae70: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
ae80: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
ae90: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
aea0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
aeb0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
aec0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
aed0: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
aee0: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
aef0: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
af00: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
af10: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a  L_VFS_POINTER]].
af20: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
af30: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
af40: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  R] opcode finds 
af50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
af60: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56   top-level.** [V
af70: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20  FSes] currently 
af80: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61  in use.  ^(The a
af90: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20  rgument X in.** 
afa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
afb0: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46  trol(db,SQLITE_F
afc0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
afd0: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f  ,X) must be.** o
afe0: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33  f type "[sqlite3
aff0: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73  _vfs] **".  This
b000: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65   opcodes will se
b010: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69  t *X.** to a poi
b020: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
b030: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20  level VFS.)^.** 
b040: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20  ^When there are 
b050: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69  multiple VFS shi
b060: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c  ms in the stack,
b070: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e   this opcode fin
b080: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d  ds the.** upper-
b090: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a  most shim only..
b0a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b0b0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b0c0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
b0d0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
b0e0: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
b0f0: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
b100: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
b110: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
b120: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
b130: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
b140: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
b150: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
b160: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
b170: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
b180: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
b190: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
b1a0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
b1b0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b1c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
b1d0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
b1e0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
b1f0: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
b200: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
b210: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
b220: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
b230: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
b240: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
b250: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
b260: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
b270: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
b280: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
b290: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
b2a0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
b2b0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
b2c0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b2d0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
b2e0: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
b2f0: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
b300: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
b310: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
b320: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
b330: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b340: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
b350: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
b360: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
b370: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
b380: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
b390: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
b3a0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
b3b0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
b3c0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
b3d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b3e0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b3f0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
b400: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
b410: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
b420: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
b430: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
b440: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b450: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b460: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b470: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
b480: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
b490: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
b4a0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
b4b0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
b4c0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
b4d0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
b4e0: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
b4f0: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72  d statement if r
b500: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20  esult string is 
b510: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65  NULL, or that re
b520: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20  turns a copy.** 
b530: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74  of the result st
b540: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69  ring if the stri
b550: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a  ng is non-NULL..
b560: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
b570: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b580: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b590: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
b5a0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
b5b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
b5c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
b5d0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
b5e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
b5f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
b600: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
b610: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
b620: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
b630: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
b640: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
b650: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
b660: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b670: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b680: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
b690: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
b6a0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
b6b0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
b6c0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
b6d0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
b6e0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
b6f0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
b700: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b710: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b720: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
b730: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b740: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
b750: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
b760: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
b770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b780: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
b790: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
b7a0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
b7b0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
b7c0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
b7d0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
b7e0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
b7f0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
b800: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
b810: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
b820: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
b830: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
b840: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
b850: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
b860: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
b870: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
b880: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
b890: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
b8a0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
b8b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
b8c0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
b8d0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
b8e0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
b8f0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
b900: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
b910: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
b920: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
b930: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
b940: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
b950: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
b960: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
b970: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
b980: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
b990: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
b9a0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
b9b0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
b9c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b9d0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b9e0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
b9f0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ba00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ba10: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ba20: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ba30: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ba40: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ba50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ba60: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ba70: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ba80: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ba90: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
baa0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
bab0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
bac0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
bad0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
bae0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
baf0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
bb00: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
bb10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
bb20: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
bb30: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
bb40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
bb50: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
bb60: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
bb70: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
bb80: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
bb90: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
bba0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
bbb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bbc0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
bbd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bbe0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
bbf0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
bc00: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
bc10: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
bc20: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
bc30: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
bc40: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
bc50: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
bc60: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
bc70: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
bc80: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
bc90: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
bca0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
bcb0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
bcc0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
bcd0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
bce0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
bcf0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
bd00: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
bd10: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
bd20: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
bd30: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
bd40: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
bd50: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
bd60: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
bd70: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
bd80: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
bd90: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
bda0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
bdb0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
bdc0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
bdd0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
bde0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
bdf0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
be00: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
be10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
be20: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
be30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
be40: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
be50: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
be60: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
be70: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
be80: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
be90: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
bea0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
beb0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
bec0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
bed0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
bee0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
bef0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
bf00: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
bf10: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
bf20: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
bf30: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
bf40: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
bf50: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
bf60: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
bf70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
bf80: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
bf90: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
bfa0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
bfb0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
bfc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bfd0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
bfe0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
bff0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
c000: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
c010: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
c020: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
c030: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
c040: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
c050: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
c060: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
c070: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
c080: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
c090: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
c0a0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
c0b0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
c0c0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
c0d0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
c0e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c0f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c100: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c110: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c120: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_GET_HANDLE] o
c130: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
c140: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a  d to obtain the.
c150: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61  ** underlying na
c160: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c170: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
c180: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20   a file handle. 
c190: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f   This file.** co
c1a0: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
c1b0: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
c1c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
c1d0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
c1e0: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73  le and.** writes
c1f0: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76   the resulting v
c200: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a  alue there..**.*
c210: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c220: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c230: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c240: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c250: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
c260: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
c270: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
c280: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
c290: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
c2a0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
c2b0: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
c2c0: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
c2d0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
c2e0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
c2f0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
c300: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
c310: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
c320: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
c330: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
c340: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
c350: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
c360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c370: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d  CNTL_WAL_BLOCK]]
c380: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c390: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c3a0: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20   is a signal to 
c3b0: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68  the VFS layer th
c3c0: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62  at it might.** b
c3d0: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74  e advantageous t
c3e0: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e  o block on the n
c3f0: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20  ext WAL lock if 
c400: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20  the lock is not 
c410: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61  immediately.** a
c420: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57  vailable.  The W
c430: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73  AL subsystem iss
c440: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20  ues this signal 
c450: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63  during rare.** c
c460: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20  ircumstances in 
c470: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70  order to fix a p
c480: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f  roblem with prio
c490: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a  rity inversion..
c4a0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
c4b0: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f  should <em>not</
c4c0: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c  em> use this fil
c4d0: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a  e-control..**.**
c4e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c4f0: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20  NTL_ZIPVFS]].** 
c500: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c510: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65  L_ZIPVFS] opcode
c520: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c530: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20  by zipvfs only. 
c540: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53  All other.** VFS
c550: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c560: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c570: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  or this opcode..
c580: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c590: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a  TE_FCNTL_RBU]].*
c5a0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c5b0: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20  NTL_RBU] opcode 
c5c0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c5d0: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  y the special VF
c5e0: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65  S used by.** the
c5f0: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f   RBU extension o
c600: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  nly.  All other 
c610: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c620: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c630: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70  D for.** this op
c640: 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  code.  .**.** <l
c650: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c660: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c670: 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20  ITE]].** If the 
c680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
c690: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
c6a0: 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73  ] opcode returns
c6b0: 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e   SQLITE_OK, then
c6c0: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73  .** the file des
c6d0: 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65  criptor is place
c6e0: 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74  d in "batch writ
c6f0: 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a  e mode", which.*
c700: 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73  * means all subs
c710: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65  equent write ope
c720: 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20  rations will be 
c730: 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e  deferred and don
c740: 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20  e.** atomically 
c750: 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c  at the next [SQL
c760: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c770: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20  _ATOMIC_WRITE]. 
c780: 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74   Systems.** that
c790: 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
c7a0: 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69  batch atomic wri
c7b0: 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  tes will return 
c7c0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e  SQLITE_NOTFOUND.
c7d0: 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61  .** ^Following a
c7e0: 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49   successful SQLI
c7f0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c800: 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20  TOMIC_WRITE and 
c810: 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20  prior to.** the 
c820: 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  closing [SQLITE_
c830: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c840: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a  MIC_WRITE] or.**
c850: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
c860: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
c870: 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69  RITE], SQLite wi
c880: 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46  ll make.** no VF
c890: 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  S interface call
c8a0: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73  s on the same [s
c8b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c  qlite3_file] fil
c8c0: 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20  e descriptor.** 
c8d0: 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73  except for calls
c8e0: 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d   to the xWrite m
c8f0: 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46  ethod and the xF
c900: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c910: 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54  d.** with [SQLIT
c920: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
c930: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  T]..**.** <li>[[
c940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c950: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
c960: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c970: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c980: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63  TOMIC_WRITE] opc
c990: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77  ode causes all w
c9a0: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  rite.** operatio
c9b0: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65  ns since the pre
c9c0: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c  vious successful
c9d0: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51   call to .** [SQ
c9e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c9f0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74  _ATOMIC_WRITE] t
ca00: 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61  o be performed a
ca10: 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68  tomically..** Th
ca20: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
ca30: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
ca40: 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  OK] if and only 
ca50: 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65  if the writes we
ca60: 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72  re.** all perfor
ca70: 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  med successfully
ca80: 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63   and have been c
ca90: 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73  ommitted to pers
caa0: 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a  istent storage..
cab0: 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
cac0: 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
cad0: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
cae0: 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  l, this file con
caf0: 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68  trol takes.** th
cb00: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
cb10: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77  r out of batch w
cb20: 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61  rite mode so tha
cb30: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
cb40: 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74  .** write operat
cb50: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e  ions are indepen
cb60: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  dent..** ^SQLite
cb70: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
cb80: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ke SQLITE_FCNTL_
cb90: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
cba0: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
cbb0: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cbc0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
cbd0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cbe0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
cbf0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cc00: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
cc10: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
cc20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
cc30: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
cc40: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
cc50: 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74   causes all writ
cc60: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20  e.** operations 
cc70: 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f  since the previo
cc80: 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  us successful ca
cc90: 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54  ll to .** [SQLIT
cca0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
ccb0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62  OMIC_WRITE] to b
ccc0: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  e rolled back..*
ccd0: 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  * ^This file con
cce0: 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66  trol takes the f
ccf0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f  ile descriptor o
cd00: 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74  ut of batch writ
cd10: 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61  e mode.** so tha
cd20: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
cd30: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
cd40: 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e  s are independen
cd50: 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  t..** ^SQLite wi
cd60: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
cd70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
cd80: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
cd90: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  TE without.** a 
cda0: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
cdb0: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45   call to [SQLITE
cdc0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cdd0: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a  MIC_WRITE]..**.*
cde0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
cdf0: 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55  CNTL_LOCK_TIMEOU
ce00: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
ce10: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49  TE_FCNTL_LOCK_TI
ce20: 4d 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61  MEOUT] opcode ca
ce30: 75 73 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f  uses attempts to
ce40: 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c   obtain.** a fil
ce50: 65 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65  e lock using the
ce60: 20 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f   xLock or xShmLo
ce70: 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  ck methods of th
ce80: 65 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a  e VFS to wait.**
ce90: 20 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c   for up to M mil
cea0: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
ceb0: 20 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20   failing, where 
cec0: 4d 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20  M is the single 
ced0: 0a 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  .** unsigned int
cee0: 65 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a  eger parameter..
cef0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
cf00: 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45  TE_FCNTL_DATA_VE
cf10: 52 53 49 4f 4e 5d 5d 0a 2a 2a 20 54 68 65 20 5b  RSION]].** The [
cf20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54  SQLITE_FCNTL_DAT
cf30: 41 5f 56 45 52 53 49 4f 4e 5d 20 6f 70 63 6f 64  A_VERSION] opcod
cf40: 65 20 69 73 20 75 73 65 64 20 74 6f 20 64 65 74  e is used to det
cf50: 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
cf60: 2a 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  * a database fil
cf70: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
cf80: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
cf90: 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
cfa0: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  ed integer..** T
cfb0: 68 65 20 22 64 61 74 61 20 76 65 72 73 69 6f 6e  he "data version
cfc0: 22 20 66 6f 72 20 74 68 65 20 70 61 67 65 72 20  " for the pager 
cfd0: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
cfe0: 74 68 65 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  the pointer.  Th
cff0: 65 0a 2a 2a 20 22 64 61 74 61 20 76 65 72 73 69  e.** "data versi
d000: 6f 6e 22 20 63 68 61 6e 67 65 73 20 77 68 65 6e  on" changes when
d010: 65 76 65 72 20 61 6e 79 20 63 68 61 6e 67 65 20  ever any change 
d020: 6f 63 63 75 72 73 20 74 6f 20 74 68 65 20 63 6f  occurs to the co
d030: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 64  rresponding.** d
d040: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 65 69  atabase file, ei
d050: 74 68 65 72 20 74 68 72 6f 75 67 68 20 53 51 4c  ther through SQL
d060: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
d070: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
d080: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  .** connection o
d090: 72 20 74 68 72 6f 75 67 68 20 74 72 61 6e 73 61  r through transa
d0a0: 63 74 69 6f 6e 73 20 63 6f 6d 6d 69 74 74 65 64  ctions committed
d0b0: 20 62 79 20 73 65 70 61 72 61 74 65 20 64 61 74   by separate dat
d0c0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
d0d0: 69 6f 6e 73 20 70 6f 73 73 69 62 6c 79 20 69 6e  ions possibly in
d0e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
d0f0: 2e 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  . The [sqlite3_t
d100: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
d110: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  ** interface can
d120: 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
d130: 20 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 65   if any database
d140: 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   on the connecti
d150: 6f 6e 20 68 61 73 20 63 68 61 6e 67 65 64 2c 0a  on has changed,.
d160: 2a 2a 20 62 75 74 20 74 68 61 74 20 69 6e 74 65  ** but that inte
d170: 72 66 61 63 65 20 72 65 73 70 6f 6e 64 73 20 74  rface responds t
d180: 6f 20 63 68 61 6e 67 65 73 20 6f 6e 20 54 45 4d  o changes on TEM
d190: 50 20 61 73 20 77 65 6c 6c 20 61 73 20 4d 41 49  P as well as MAI
d1a0: 4e 20 61 6e 64 20 64 6f 65 73 0a 2a 2a 20 6e 6f  N and does.** no
d1b0: 74 20 70 72 6f 76 69 64 65 20 61 20 6d 65 63 68  t provide a mech
d1c0: 61 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20  anism to detect 
d1d0: 63 68 61 6e 67 65 73 20 74 6f 20 4d 41 49 4e 20  changes to MAIN 
d1e0: 6f 6e 6c 79 2e 20 20 41 6c 73 6f 2c 20 74 68 65  only.  Also, the
d1f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
d200: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
d210: 74 65 72 66 61 63 65 20 72 65 73 70 6f 6e 64 73  terface responds
d220: 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 63 68 61   to internal cha
d230: 6e 67 65 73 20 6f 6e 6c 79 20 61 6e 64 0a 2a 2a  nges only and.**
d240: 20 6f 6d 69 74 73 20 63 68 61 6e 67 65 73 20 6d   omits changes m
d250: 61 64 65 20 62 79 20 6f 74 68 65 72 20 64 61 74  ade by other dat
d260: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d270: 73 2e 20 20 54 68 65 0a 2a 2a 20 5b 50 52 41 47  s.  The.** [PRAG
d280: 4d 41 20 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d  MA data_version]
d290: 20 63 6f 6d 6d 61 6e 64 20 70 72 6f 76 69 64 65   command provide
d2a0: 20 61 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20   a mechanism to 
d2b0: 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 74  detect changes t
d2c0: 6f 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 61 74  o.** a single at
d2d0: 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20  tached database 
d2e0: 74 68 61 74 20 6f 63 63 75 72 20 64 75 65 20 74  that occur due t
d2f0: 6f 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65  o other database
d300: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 0a 2a 2a   connections,.**
d310: 20 62 75 74 20 6f 6d 69 74 73 20 63 68 61 6e 67   but omits chang
d320: 65 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  es implemented b
d330: 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
d340: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 6e 20 77 68 69  onnection on whi
d350: 63 68 20 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c  ch it is.** call
d360: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 20 63  ed.  This file c
d370: 6f 6e 74 72 6f 6c 20 69 73 20 74 68 65 20 6f 6e  ontrol is the on
d380: 6c 79 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20  ly mechanism to 
d390: 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 74  detect changes t
d3a0: 68 61 74 0a 2a 2a 20 68 61 70 70 65 6e 20 65 69  hat.** happen ei
d3b0: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
d3c0: 6f 72 20 65 78 74 65 72 6e 61 6c 6c 79 20 61 6e  or externally an
d3d0: 64 20 74 68 61 74 20 61 72 65 20 61 73 73 6f 63  d that are assoc
d3e0: 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 61 20  iated with.** a 
d3f0: 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 61 63  particular attac
d400: 68 65 64 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  hed database..**
d410: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
d420: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
d430: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
d440: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
d450: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
d460: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
d470: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
d480: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
d490: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
d4a0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
d4b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
d4c0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
d4d0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
d4e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
d4f0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
d500: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
d510: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
d520: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
d530: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
d540: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
d550: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
d560: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
d570: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
d580: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
d590: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
d5a0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
d5b0: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
d5c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d5d0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
d5e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
d5f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d600: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
d610: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
d620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d630: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
d640: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
d650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d660: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
d670: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
d680: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d690: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
d6a0: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
d6b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d6c0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
d6d0: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
d6e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d6f0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
d700: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e         16.#defin
d710: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  e SQLITE_FCNTL_M
d720: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20  MAP_SIZE        
d730: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65        18.#define
d740: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52   SQLITE_FCNTL_TR
d750: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ACE             
d760: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20       19.#define 
d770: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
d780: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20  _MOVED          
d790: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53      20.#define S
d7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d7b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d7c0: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51     21.#define SQ
d7d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d7e0: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20  T_PHASETWO      
d7f0: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    22.#define SQL
d800: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d810: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  SET_HANDLE      
d820: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   23.#define SQLI
d830: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
d840: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
d850: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  24.#define SQLIT
d860: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20  E_FCNTL_ZIPVFS  
d870: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d880: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
d890: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20  _FCNTL_RBU      
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36                26
d8b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d8c0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
d8d0: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a  R            27.
d8e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d8f0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
d900: 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23  NTER        28.#
d910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d920: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
d930: 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64  NDLE       29.#d
d940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d950: 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20  TL_PDB          
d960: 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65            30.#de
d970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d980: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
d990: 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66  RITE     31.#def
d9a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d9b0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
d9c0: 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69  RITE    32.#defi
d9d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d9e0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
d9f0: 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 69 6e  WRITE  33.#defin
da00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
da10: 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20 20  OCK_TIMEOUT     
da20: 20 20 20 20 20 20 33 34 0a 23 64 65 66 69 6e 65        34.#define
da30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41   SQLITE_FCNTL_DA
da40: 54 41 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TA_VERSION      
da50: 20 20 20 20 20 33 35 0a 0a 2f 2a 20 64 65 70 72       35../* depr
da60: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
da70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
da80: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
da90: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
daa0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
dab0: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
dac0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
dad0: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
dae0: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
daf0: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
db00: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
db10: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
db20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
db30: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
db40: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
db50: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
db60: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
db70: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
db80: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
db90: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
dba0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
dbb0: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
dbc0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
dbd0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
dbe0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
dbf0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
dc00: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
dc10: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
dc20: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
dc30: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
dc40: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
dc50: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
dc60: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
dc70: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
dc80: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
dc90: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
dca0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
dcb0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
dcc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
dcd0: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
dce0: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
dcf0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
dd00: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
dd10: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
dd20: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
dd30: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
dd40: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
dd50: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
dd60: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
dd70: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
dd80: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
dd90: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
dda0: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
ddb0: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
ddc0: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
ddd0: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
dde0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
ddf0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
de00: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
de10: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
de20: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
de30: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
de40: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
de50: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
de60: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
de70: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
de80: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
de90: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
dea0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
deb0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
dec0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
ded0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
dee0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
def0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
df00: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
df10: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
df20: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
df30: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
df40: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
df50: 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69 73  VFS interface is
df60: 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 6e   sometimes exten
df70: 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e 65  ded by adding ne
df80: 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a  w methods onto.*
df90: 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63 68  * the end.  Each
dfa0: 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65 78   time such an ex
dfb0: 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c 20  tension occurs, 
dfc0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
dfd0: 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d 65  ld.** is increme
dfe0: 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72 73  nted.  The iVers
dff0: 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74 65  ion value starte
e000: 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a 2a  d out as 1 in.**
e010: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
e020: 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 65   3.5.0] on [date
e030: 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e 20  of:3.5.0], then 
e040: 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a 2a  increased to 2.*
e050: 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76  * with SQLite [v
e060: 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e  ersion 3.7.0] on
e070: 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c   [dateof:3.7.0],
e080: 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 61   and then increa
e090: 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 68  sed.** to 3 with
e0a0: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
e0b0: 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 65   3.7.6] on [date
e0c0: 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 69  of:3.7.6].  Addi
e0d0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
e0e0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
e0f0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
e100: 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 74  vfs object and t
e110: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
e120: 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 73  e.** may increas
e130: 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75 72  e again in futur
e140: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
e150: 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  Lite..** Note th
e160: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
e170: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
e180: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
e190: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
e1a0: 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  nsition from.** 
e1b0: 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
e1c0: 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 69  3.5.9] to [versi
e1d0: 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61  on 3.6.0] on [da
e1e0: 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61  teof:3.6.0].** a
e1f0: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
e200: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
e210: 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  t modified..**.*
e220: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
e230: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
e240: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
e250: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
e260: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
e270: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
e280: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
e290: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
e2a0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
e2b0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
e2c0: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
e2d0: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
e2e0: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
e2f0: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
e300: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
e310: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
e320: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
e330: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
e340: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
e350: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
e360: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
e370: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
e380: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
e390: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
e3a0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
e3b0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
e3c0: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
e3d0: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
e3e0: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
e3f0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
e400: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
e410: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
e420: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
e430: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
e440: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
e450: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
e460: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
e470: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
e480: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
e490: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
e4a0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
e4b0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
e4c0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
e4d0: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
e4e0: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
e4f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
e500: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
e510: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
e520: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
e530: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
e540: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
e550: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
e560: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
e570: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
e580: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
e590: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
e5a0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
e5b0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
e5c0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
e5d0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
e5e0: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
e5f0: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
e600: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
e610: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
e620: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
e630: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
e640: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
e650: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
e660: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
e670: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
e680: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
e690: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
e6a0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
e6b0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
e6c0: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
e6d0: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
e6e0: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
e6f0: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
e700: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
e710: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
e720: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
e730: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
e740: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
e750: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
e760: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
e770: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
e780: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
e790: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
e7a0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
e7b0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
e7c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
e7d0: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
e7e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
e7f0: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
e800: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
e810: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
e820: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
e830: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
e840: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
e850: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
e860: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
e870: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
e880: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
e890: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
e8a0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
e8b0: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
e8c0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e8d0: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
e8e0: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
e8f0: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
e900: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
e910: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
e920: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e930: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
e940: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
e950: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
e960: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
e970: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
e980: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
e990: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
e9a0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
e9b0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
e9c0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
e9d0: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
e9e0: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
e9f0: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
ea00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ea10: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
ea20: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
ea30: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
ea40: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
ea50: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
ea60: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
ea70: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
ea80: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
ea90: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
eaa0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
eab0: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
eac0: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
ead0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
eae0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
eaf0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
eb00: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
eb10: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
eb20: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
eb30: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
eb40: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
eb50: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
eb60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
eb70: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
eb80: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
eb90: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
eba0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ebb0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
ebc0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ebd0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
ebe0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
ebf0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
ec00: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
ec10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
ec20: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
ec30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ec40: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
ec50: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
ec60: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
ec70: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
ec80: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
ec90: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
eca0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
ecb0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
ecc0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
ecd0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
ece0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
ecf0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
ed00: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
ed10: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
ed20: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
ed30: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
ed40: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
ed50: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
ed60: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
ed70: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
ed80: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
ed90: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
eda0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
edb0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
edc0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
edd0: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
ede0: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
edf0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
ee00: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
ee10: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
ee20: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
ee30: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
ee40: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
ee50: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
ee60: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
ee70: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
ee80: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
ee90: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
eea0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
eeb0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
eec0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
eed0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
eee0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
eef0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
ef00: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ef10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
ef20: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
ef30: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
ef40: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
ef50: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
ef60: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
ef70: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
ef80: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
ef90: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
efa0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
efb0: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
efc0: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
efd0: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
efe0: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
eff0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
f000: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
f010: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
f020: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
f030: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
f040: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
f050: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
f060: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
f070: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
f080: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
f090: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
f0a0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
f0b0: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
f0c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
f0d0: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
f0e0: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
f0f0: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
f100: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
f110: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
f120: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
f130: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
f140: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
f150: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
f160: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
f170: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
f180: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
f190: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
f1a0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
f1b0: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
f1c0: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
f1d0: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
f1e0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
f1f0: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
f200: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
f210: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
f220: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
f230: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
f240: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
f250: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
f260: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
f270: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
f280: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
f290: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
f2a0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
f2b0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
f2c0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
f2d0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
f2e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
f2f0: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
f300: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
f310: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
f320: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
f330: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
f340: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
f350: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
f360: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
f370: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
f380: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
f390: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
f3a0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
f3b0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
f3c0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
f3d0: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
f3e0: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
f3f0: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
f400: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
f410: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
f420: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
f430: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
f440: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
f450: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
f460: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
f470: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
f480: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
f490: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f4a0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
f4b0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
f4c0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
f4d0: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
f4e0: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
f4f0: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
f500: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
f510: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
f520: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
f530: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
f540: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
f550: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
f560: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
f570: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
f580: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
f590: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
f5a0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
f5b0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
f5c0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
f5d0: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
f5e0: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
f5f0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
f600: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
f610: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
f620: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
f630: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
f640: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
f650: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
f660: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
f670: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
f680: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
f690: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
f6a0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
f6b0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
f6c0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
f6d0: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
f6e0: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
f6f0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
f700: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
f710: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
f720: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
f730: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
f740: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
f750: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
f760: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
f770: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
f780: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
f790: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
f7a0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
f7b0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
f7c0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
f7d0: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
f7e0: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
f7f0: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
f800: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
f810: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
f820: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
f830: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
f840: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
f850: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
f860: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
f870: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
f880: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
f890: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
f8a0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
f8b0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
f8c0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
f8d0: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
f8e0: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
f8f0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
f900: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
f910: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
f920: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
f930: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
f940: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
f950: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
f960: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
f970: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
f980: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
f990: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
f9a0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
f9b0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
f9c0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
f9d0: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
f9e0: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
f9f0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
fa00: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
fa10: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
fa20: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
fa30: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
fa40: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
fa50: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
fa60: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
fa70: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
fa80: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
fa90: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
faa0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
fab0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
fac0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
fad0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
fae0: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
faf0: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
fb00: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
fb10: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
fb20: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
fb30: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
fb40: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
fb50: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
fb60: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
fb70: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
fb80: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
fb90: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
fba0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
fbb0: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
fbc0: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
fbd0: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
fbe0: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
fbf0: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
fc00: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
fc10: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
fc20: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
fc30: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
fc40: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
fc50: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
fc60: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
fc70: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
fc80: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
fc90: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
fca0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
fcb0: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
fcc0: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
fcd0: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
fce0: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
fcf0: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
fd00: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
fd10: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
fd20: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
fd30: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
fd40: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
fd50: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
fd60: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
fd70: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
fd80: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
fd90: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
fda0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
fdb0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
fdc0: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
fdd0: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
fde0: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
fdf0: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
fe00: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
fe10: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
fe20: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
fe30: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
fe40: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
fe50: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
fe60: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
fe70: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
fe80: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
fe90: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
fea0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
feb0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
fec0: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
fed0: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
fee0: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
fef0: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
ff00: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
ff10: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
ff20: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
ff30: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
ff40: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
ff50: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
ff60: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
ff70: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
ff80: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
ff90: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
ffa0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
ffb0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
ffc0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
ffd0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
ffe0: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
fff0: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
10000 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
10010 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
10020 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10030 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10040 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
10050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
10060 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
10070 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
10080 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
10090 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
100a0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
100b0 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
100c0 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
100d0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
100e0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
100f0 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
10100 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
10110 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
10120 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10130 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
10140 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
10150 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
10160 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
10170 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10180 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
10190 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
101a0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
101b0 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
101c0 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
101d0 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
101e0 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
101f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
10200 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
10210 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
10220 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10230 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
10240 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
10250 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
10260 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
10270 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
10280 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
10290 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
102a0 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
102b0 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
102c0 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
102d0 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
102e0 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
102f0 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
10300 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
10310 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
10320 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
10330 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
10340 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
10350 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
10360 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
10370 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
10380 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
10390 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
103a0 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
103b0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
103c0 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
103d0 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
103e0 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
103f0 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
10400 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
10410 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
10420 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
10430 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
10440 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
10450 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
10460 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
10470 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10480 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
10490 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
104a0 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
104b0 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
104c0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
104d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
104e0 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
104f0 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
10500 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
10510 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10520 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
10530 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
10540 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
10550 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
10560 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
10570 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
10580 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
10590 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
105a0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
105b0 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
105c0 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
105d0 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
105e0 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
105f0 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
10600 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
10610 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
10620 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
10630 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
10640 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
10650 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
10660 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
10670 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
10680 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
10690 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
106a0 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
106b0 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
106c0 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
106d0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
106e0 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
106f0 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
10700 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
10710 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10720 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
10730 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
10740 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
10750 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
10760 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
10770 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10780 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10790 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
107a0 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
107b0 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
107c0 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
107d0 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
107e0 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
107f0 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
10800 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
10810 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
10820 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
10830 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
10840 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
10850 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
10860 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
10870 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
10880 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
10890 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
108a0 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
108b0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
108c0 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
108d0 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
108e0 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
108f0 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10900 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
10910 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
10920 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10930 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
10940 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
10950 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
10960 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
10970 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
10980 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
10990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
109a0 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
109b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
109c0 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
109d0 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
109e0 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
109f0 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
10a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10a10 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
10a20 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
10a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10a40 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
10a50 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
10a60 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
10a70 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
10a80 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
10a90 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
10aa0 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
10ab0 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
10ac0 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
10ad0 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
10ae0 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
10af0 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
10b00 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
10b10 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
10b20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
10b30 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
10b40 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
10b50 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10b60 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10b70 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10b80 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
10b90 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
10ba0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10bb0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10bc0 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
10bd0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
10be0 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
10bf0 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10c00 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
10c10 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
10c20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
10c30 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
10c40 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
10c50 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
10c60 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
10c70 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
10c80 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
10c90 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
10ca0 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
10cb0 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
10cc0 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
10cd0 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
10ce0 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
10cf0 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
10d00 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
10d10 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
10d20 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
10d30 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
10d40 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
10d50 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
10d60 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
10d70 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10d80 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
10d90 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
10da0 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
10db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
10dc0 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
10dd0 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
10de0 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
10df0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
10e00 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
10e10 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
10e20 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
10e30 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
10e40 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
10e50 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
10e60 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
10e70 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
10e80 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
10e90 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
10ea0 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
10eb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10ec0 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
10ed0 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
10ee0 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
10ef0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10f00 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
10f10 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10f20 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
10f30 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
10f40 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
10f50 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
10f60 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
10f70 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
10f80 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
10f90 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
10fa0 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
10fb0 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
10fc0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
10fd0 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
10fe0 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
10ff0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
11000 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
11010 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
11020 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
11030 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
11040 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
11050 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
11060 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
11070 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
11080 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
11090 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
110a0 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
110b0 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
110c0 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
110d0 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
110e0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
110f0 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
11100 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
11110 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
11120 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
11130 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
11140 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
11150 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
11160 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
11170 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11180 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
11190 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
111a0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
111b0 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
111c0 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
111d0 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
111e0 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
111f0 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
11200 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
11210 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11220 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
11230 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
11240 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
11250 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11260 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
11270 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
11280 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
11290 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
112a0 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
112b0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
112c0 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
112d0 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
112e0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
112f0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
11300 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
11310 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
11320 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
11330 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11340 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
11350 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
11360 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11370 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
11380 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11390 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
113a0 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
113b0 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
113c0 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
113d0 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
113e0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
113f0 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
11400 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
11410 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
11420 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
11430 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
11440 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
11450 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
11460 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
11470 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
11480 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
11490 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
114a0 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
114b0 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
114c0 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
114d0 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
114e0 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
114f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
11500 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
11510 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
11520 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
11530 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
11540 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
11550 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11560 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
11570 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
11580 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
11590 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
115a0 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
115b0 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
115c0 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
115d0 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
115e0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
115f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
11600 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
11610 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11620 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
11630 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
11640 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
11650 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
11660 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
11670 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
11680 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
11690 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
116a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
116b0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
116c0 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
116d0 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
116e0 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
116f0 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
11700 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
11710 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
11720 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
11730 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
11740 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
11750 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
11760 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
11770 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
11780 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
11790 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
117a0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
117b0 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
117c0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
117d0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
117e0 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
117f0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
11800 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
11810 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
11820 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
11830 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
11840 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
11850 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
11860 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
11870 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11880 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
11890 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
118a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
118b0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
118c0 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
118d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
118e0 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
118f0 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
11900 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
11910 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
11920 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
11930 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
11940 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
11950 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
11960 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
11970 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
11980 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11990 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
119a0 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
119b0 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
119c0 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
119d0 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
119e0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
119f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
11a00 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
11a10 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
11a20 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
11a30 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
11a40 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
11a50 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
11a60 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
11a70 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
11a80 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
11a90 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
11aa0 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
11ab0 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
11ac0 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
11ad0 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
11ae0 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
11af0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
11b00 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
11b10 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
11b20 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
11b30 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
11b40 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
11b50 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
11b60 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
11b70 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
11b80 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
11b90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11ba0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
11bb0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
11bc0 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
11bd0 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
11be0 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
11bf0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
11c00 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
11c10 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
11c20 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
11c30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11c40 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
11c50 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
11c60 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
11c70 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
11c80 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
11c90 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
11ca0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11cb0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
11cc0 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
11cd0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
11ce0 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
11cf0 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
11d00 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
11d10 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
11d20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
11d30 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
11d40 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
11d50 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
11d60 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
11d70 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
11d80 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
11d90 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
11da0 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
11db0 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
11dc0 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
11dd0 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
11de0 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
11df0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11e00 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
11e10 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
11e20 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
11e30 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
11e40 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
11e50 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
11e60 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
11e70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
11e80 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11e90 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
11ea0 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
11eb0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
11ec0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
11ed0 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
11ee0 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
11ef0 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
11f00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11f10 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
11f20 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
11f30 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
11f40 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
11f50 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
11f60 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
11f70 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11f80 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
11f90 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
11fa0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
11fb0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11fc0 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
11fd0 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
11fe0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11ff0 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
12000 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
12010 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
12020 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
12030 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
12040 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
12050 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
12060 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
12070 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
12080 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
12090 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
120a0 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
120b0 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
120c0 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
120d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
120e0 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
120f0 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
12100 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12110 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
12120 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
12130 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
12140 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
12150 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
12160 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
12170 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
12180 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
12190 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
121a0 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
121b0 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
121c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
121d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
121e0 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
121f0 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
12200 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
12210 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
12220 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
12230 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
12240 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
12250 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
12260 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
12270 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
12280 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
12290 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
122a0 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
122b0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
122c0 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
122d0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
122e0 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
122f0 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
12300 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
12310 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
12320 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
12330 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
12340 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
12350 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
12360 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
12370 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12380 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
12390 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
123a0 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
123b0 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
123c0 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
123d0 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
123e0 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
123f0 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
12400 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
12410 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
12420 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
12430 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12440 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
12450 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
12460 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
12470 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
12480 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
12490 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
124a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
124b0 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
124c0 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
124d0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
124e0 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
124f0 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
12500 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
12510 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
12520 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
12530 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
12540 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
12550 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
12560 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
12570 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
12580 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
12590 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
125a0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
125b0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
125c0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
125d0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
125e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
125f0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
12600 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
12610 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
12620 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
12630 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
12640 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
12650 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
12660 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
12670 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
12680 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
12690 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
126a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
126b0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
126c0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
126d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
126e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
126f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
12700 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
12710 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
12720 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
12730 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
12740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12750 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
12760 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
12770 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
12780 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
12790 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
127a0 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
127b0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
127c0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
127d0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
127e0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
127f0 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
12800 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
12810 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
12820 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
12830 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
12840 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
12850 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
12860 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
12870 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
12880 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12890 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
128a0 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
128b0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
128c0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
128d0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
128e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
128f0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
12900 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
12910 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
12920 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
12930 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12940 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
12950 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
12960 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
12970 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
12980 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12990 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
129a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
129b0 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
129c0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
129d0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
129e0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
129f0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12a00 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
12a10 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
12a20 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
12a30 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
12a40 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
12a50 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
12a60 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
12a70 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
12a80 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
12a90 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
12aa0 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
12ab0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
12ac0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
12ad0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
12ae0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
12af0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
12b00 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
12b10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
12b20 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
12b30 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
12b40 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
12b50 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
12b60 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
12b70 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
12b80 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
12b90 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
12ba0 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
12bb0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
12bc0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
12bd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12be0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
12bf0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
12c00 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
12c10 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
12c20 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
12c30 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12c40 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12c50 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
12c60 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
12c70 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
12c80 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
12c90 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
12ca0 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
12cb0 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
12cc0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
12cd0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
12ce0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
12cf0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
12d00 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
12d10 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
12d20 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
12d30 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
12d40 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
12d50 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
12d60 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
12d70 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
12d80 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12d90 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
12da0 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
12db0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
12dc0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
12dd0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
12de0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
12df0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
12e00 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
12e10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12e20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
12e30 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
12e40 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
12e50 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
12e60 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
12e70 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
12e80 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
12e90 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
12ea0 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
12eb0 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
12ec0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
12ed0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
12ee0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
12ef0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12f00 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
12f10 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
12f20 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
12f30 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
12f40 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
12f50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
12f60 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
12f70 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
12f80 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
12f90 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12fa0 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
12fb0 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
12fc0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
12fd0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
12fe0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
12ff0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
13000 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13010 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
13020 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
13030 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
13040 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
13050 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
13060 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
13070 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
13080 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
13090 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
130a0 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
130b0 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
130c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
130d0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
130e0 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
130f0 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
13100 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
13110 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
13120 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
13130 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
13140 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
13150 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
13160 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
13170 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
13180 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
13190 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
131a0 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
131b0 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
131c0 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
131d0 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
131e0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
131f0 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
13200 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
13210 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
13220 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
13230 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
13240 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
13250 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
13260 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
13270 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
13280 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
13290 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
132a0 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
132b0 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
132c0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
132d0 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
132e0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
132f0 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
13300 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
13310 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
13320 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
13330 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
13340 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
13350 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
13360 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13370 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
13380 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
13390 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
133a0 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
133b0 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
133c0 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
133d0 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
133e0 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
133f0 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
13400 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
13410 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
13420 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
13430 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
13440 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
13450 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
13460 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
13470 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
13480 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
13490 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
134a0 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
134b0 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
134c0 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
134d0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
134e0 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
134f0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
13500 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
13510 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13520 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
13530 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
13540 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
13550 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
13560 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
13570 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
13580 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
13590 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
135a0 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
135b0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
135c0 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
135d0 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
135e0 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
135f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
13600 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
13610 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
13620 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
13630 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
13640 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
13650 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
13660 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
13670 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
13680 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
13690 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
136a0 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
136b0 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
136c0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
136d0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
136e0 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
136f0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
13700 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
13710 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13720 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
13730 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
13740 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
13750 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
13760 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
13770 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
13780 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
13790 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
137a0 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
137b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
137c0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
137d0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
137e0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
137f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13800 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
13810 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
13820 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13830 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
13840 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
13850 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
13860 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13870 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
13880 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
13890 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
138a0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
138b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
138c0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
138d0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
138e0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
138f0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
13900 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
13910 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13920 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
13930 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
13940 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
13950 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13960 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
13970 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13980 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13990 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
139a0 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
139b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
139c0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
139d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
139e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
139f0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
13a00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13a10 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
13a20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
13a30 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
13a40 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13a50 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13a60 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13a70 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13a80 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
13a90 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13aa0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
13ab0 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
13ac0 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
13ad0 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
13ae0 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
13af0 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
13b00 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
13b10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13b20 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13b30 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13b40 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13b50 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13b60 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13b70 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13b80 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
13b90 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
13ba0 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
13bb0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
13bc0 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
13bd0 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
13be0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
13bf0 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
13c00 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
13c10 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
13c20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13c30 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
13c40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13c50 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13c60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13c70 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
13c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
13c90 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
13ca0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
13cb0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
13cc0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
13cd0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13ce0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13cf0 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
13d00 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
13d10 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
13d20 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
13d30 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
13d40 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
13d50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13d60 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
13d70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
13d80 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
13d90 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
13da0 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
13db0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13dc0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13dd0 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
13de0 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
13df0 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
13e00 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
13e10 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
13e20 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
13e30 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
13e40 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
13e50 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
13e60 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
13e70 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
13e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13e90 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13ea0 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
13eb0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13ec0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13ed0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13ee0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13ef0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13f00 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
13f10 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
13f20 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
13f30 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
13f40 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
13f50 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13f60 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13f70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13f80 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13f90 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13fa0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
13fb0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13fc0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
13fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13fe0 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
13ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14000 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
14010 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
14020 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
14030 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
14040 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14050 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14060 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
14070 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
14080 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
14090 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
140a0 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
140b0 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
140c0 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
140d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
140e0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
140f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
14100 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
14110 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
14120 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
14130 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14140 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
14150 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
14160 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
14170 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
14180 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
14190 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
141a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
141b0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
141c0 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
141d0 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
141e0 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
141f0 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
14200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14210 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
14220 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
14230 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
14240 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
14250 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
14260 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14270 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14280 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14290 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
142a0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
142b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
142c0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
142d0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
142e0 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
142f0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
14300 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
14310 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14320 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
14330 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
14340 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
14350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14360 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
14370 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
14380 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14390 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
143a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
143b0 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
143c0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
143d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
143e0 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
143f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14400 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
14410 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14420 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14430 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14440 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14450 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
14460 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
14470 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
14480 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
14490 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
144a0 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
144b0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
144c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
144d0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
144e0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
144f0 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
14500 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
14510 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
14520 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14530 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
14540 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
14550 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
14560 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
14570 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
14580 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14590 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
145a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
145b0 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
145c0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
145d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
145e0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
145f0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14600 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14610 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14620 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14630 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
14640 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
14650 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
14660 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
14670 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
14680 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
14690 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
146a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
146b0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
146c0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
146d0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
146e0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
146f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14700 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
14710 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
14720 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
14730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14740 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
14750 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
14760 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
14770 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14790 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  LL_MALLOC]] <dt>
147a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
147b0 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  ALL_MALLOC</dt>.
147c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
147d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
147e0 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  _MALLOC option t
147f0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
14800 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20  ment of.** type 
14810 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
14820 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
14830 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f  hich if true pro
14840 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a  vides a hint to.
14850 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  ** SQLite that i
14860 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c  t should avoid l
14870 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  arge memory allo
14880 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69  cations if possi
14890 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ble..** SQLite w
148a0 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69  ill run faster i
148b0 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20  f it is free to 
148c0 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72  make large memor
148d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a  y allocations,.*
148e0 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69  * but some appli
148f0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65  cation might pre
14900 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65  fer to run slowe
14910 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f  r in exchange fo
14920 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  r.** guarantees 
14930 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61  about memory fra
14940 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  gmentation that 
14950 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20  are possible if 
14960 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  large.** allocat
14970 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64  ions are avoided
14980 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
14990 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a  normally off..**
149a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
149b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
149c0 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
149d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
149e0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
149f0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14a00 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
14a10 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
14a20 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
14a30 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
14a40 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
14a50 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
14a60 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
14a70 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
14a80 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
14a90 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14aa0 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
14ab0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14ac0 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
14ad0 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
14ae0 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
14af0 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
14b00 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
14b10 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
14b20 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
14b30 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
14b40 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
14b50 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
14b60 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
14b70 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
14b80 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
14b90 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
14ba0 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
14bb0 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
14bc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14bd0 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
14be0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
14bf0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
14c00 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
14c10 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
14c20 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
14c30 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
14c40 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
14c50 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
14c60 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
14c70 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
14c80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14c90 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
14ca0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14cb0 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
14cc0 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
14cd0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
14ce0 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ption is no long
14cf0 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64  er used..** </dd
14d00 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14d10 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14d20 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
14d30 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
14d40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14d50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d60 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
14d70 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d   specifies a mem
14d80 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74  ory pool.** that
14d90 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
14da0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
14db0 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
14dc0 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
14dd0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
14de0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
14df0 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
14e00 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e  on option is a n
14e10 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69  o-op if an appli
14e20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
14e30 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
14e40 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
14e50 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
14e60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14e70 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72  ACHE2]..** ^Ther
14e80 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
14e90 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
14ea0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14eb0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  : A pointer to.*
14ec0 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  * 8-byte aligned
14ed0 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20   memory (pMem), 
14ee0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
14ef0 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
14f00 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
14f10 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68  e number of cach
14f20 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20  e lines (N)..** 
14f30 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
14f40 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
14f50 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
14f60 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
14f70 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
14f80 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
14f90 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
14fa0 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
14fb0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
14fc0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
14fd0 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
14fe0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
14ff0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
15000 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
15010 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54  ned using [SQLIT
15020 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
15030 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69  HDRSZ]..** ^It i
15040 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
15050 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
15060 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
15070 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
15080 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
15090 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
150a0 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75  The pMem.** argu
150b0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74  ment must be eit
150c0 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
150d0 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  er or a pointer 
150e0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
150f0 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66  aligned block of
15100 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65   memory of at le
15110 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20  ast sz*N bytes, 
15120 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62  otherwise.** sub
15130 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
15140 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
15150 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20  * ^When pMem is 
15160 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
15170 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20   will strive to 
15180 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
15190 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61  rovided.** to sa
151a0 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65  tisfy page cache
151b0 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20   needs, falling 
151c0 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33  back to [sqlite3
151d0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a  _malloc()] if.**
151e0 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69   a page cache li
151f0 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61  ne is larger tha
15200 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66  n sz bytes or if
15210 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d   all of the pMem
15220 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78   buffer.** is ex
15230 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20  hausted..** ^If 
15240 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64  pMem is NULL and
15250 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20   N is non-zero, 
15260 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61  then each databa
15270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
15280 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c   does an initial
15290 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e   bulk allocation
152a0 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
152b0 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b  memory.** from [
152c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
152d0 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72  ] sufficient for
152e0 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69   N cache lines i
152f0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20  f N is positive 
15300 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e  or.** of -1024*N
15310 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e   bytes if N is n
15320 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61  egative, . ^If a
15330 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
15340 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
15350 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
15360 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
15370 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a   by the initial.
15380 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ** allocation, t
15390 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20  hen SQLite goes 
153a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
153b0 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79  oc()] separately
153c0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64   for each.** add
153d0 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69  itional cache li
153e0 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ne. </dd>.**.** 
153f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15400 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
15410 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
15420 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
15430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
15440 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
15450 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
15460 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
15470 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
15480 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
15490 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
154a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
154b0 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
154c0 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
154d0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
154e0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
154f0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
15500 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
15510 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15520 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
15530 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
15540 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
15550 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
15560 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
15570 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
15580 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
15590 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
155a0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
155b0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
155c0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
155d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
155e0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
155f0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
15600 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
15610 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
15620 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
15630 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
15640 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
15650 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
15660 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
15670 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
15680 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
15690 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
156a0 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
156b0 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
156c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
156d0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
156e0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
156f0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
15700 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
15710 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
15720 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
15730 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
15740 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
15750 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
15760 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
15770 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
15780 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
15790 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
157a0 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
157b0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
157c0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
157d0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
157e0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
157f0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15800 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
15810 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
15820 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
15830 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
15840 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
15850 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
15860 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
15870 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
15880 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
15890 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
158a0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
158b0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
158c0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
158d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
158e0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
158f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
15900 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15910 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15920 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
15930 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15940 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
15950 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15960 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
15970 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15980 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15990 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
159a0 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
159b0 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
159c0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
159d0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
159e0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
159f0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
15a00 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
15a10 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
15a20 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
15a30 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
15a40 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15a50 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15a60 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
15a70 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
15a80 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
15a90 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
15aa0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15ab0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15ac0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15ad0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15ae0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15af0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
15b00 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
15b10 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
15b20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
15b30 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
15b40 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
15b50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15b60 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
15b70 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
15b80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15b90 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15ba0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
15bb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15bd0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
15be0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15bf0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
15c00 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15c10 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
15c20 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15c30 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
15c40 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15c50 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
15c60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15c70 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
15c80 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
15c90 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
15ca0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
15cb0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
15cc0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
15cd0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
15ce0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
15cf0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
15d00 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
15d10 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
15d20 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
15d30 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
15d40 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
15d50 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
15d60 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
15d70 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
15d80 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
15d90 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
15da0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15db0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
15dc0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15dd0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
15de0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
15df0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15e00 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
15e10 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
15e20 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
15e30 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
15e40 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
15e50 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15e60 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
15e70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15e80 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
15e90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
15ea0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
15eb0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
15ec0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15ed0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
15ee0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
15ef0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
15f00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15f10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15f20 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
15f30 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
15f40 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
15f50 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
15f60 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
15f70 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
15f80 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
15f90 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
15fa0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15fb0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
15fc0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
15fd0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
15fe0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
15ff0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16000 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
16010 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
16020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
16030 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
16040 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
16050 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
16060 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
16070 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
16080 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16090 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
160a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
160b0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
160c0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
160d0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
160e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
160f0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
16100 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
16110 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16120 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
16130 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16140 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
16150 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
16160 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16170 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
16180 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16190 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
161a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
161b0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
161c0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
161d0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
161e0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
161f0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
16200 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
16210 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
16220 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
16230 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
16240 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
16250 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16260 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
16270 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16280 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
16290 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
162a0 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
162b0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
162c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
162d0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
162e0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
162f0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
16300 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16310 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
16320 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
16330 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
16340 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
16350 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
16360 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
16370 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
16380 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
16390 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
163a0 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
163b0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
163c0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
163d0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
163e0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
163f0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
16400 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
16410 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
16420 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16430 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
16440 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
16450 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
16460 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
16470 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
16480 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
16490 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
164a0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
164b0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
164c0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
164d0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
164e0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
164f0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
16500 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
16510 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
16520 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
16530 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
16540 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
16550 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
16560 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
16570 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
16580 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
16590 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
165a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
165b0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
165c0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
165d0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
165e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
165f0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
16600 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
16610 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
16620 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
16630 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
16640 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
16650 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
16660 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
16670 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
16680 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16690 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
166a0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
166b0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
166c0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
166d0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
166e0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
166f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
16700 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
16710 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
16720 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
16730 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
16740 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
16750 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
16760 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
16770 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
16780 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
16790 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
167a0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
167b0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
167c0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
167d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
167e0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
167f0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
16800 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
16810 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
16820 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
16830 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
16840 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
16850 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
16860 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16870 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
16880 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16890 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
168a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
168b0 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
168c0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
168d0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
168e0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
168f0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16900 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
16910 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
16920 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
16930 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
16940 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16950 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
16960 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
16970 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
16980 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
16990 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
169a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
169b0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
169c0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
169d0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
169e0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
169f0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
16a00 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
16a10 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
16a20 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
16a30 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
16a40 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
16a50 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
16a60 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
16a70 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
16a80 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
16a90 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
16aa0 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
16ab0 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
16ac0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
16ad0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
16ae0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
16af0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
16b00 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
16b10 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
16b20 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
16b30 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
16b40 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
16b50 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
16b60 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
16b70 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
16b80 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
16b90 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
16ba0 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
16bb0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
16bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
16bd0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
16be0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16bf0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
16c00 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
16c10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16c20 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16c30 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
16c40 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
16c50 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
16c60 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
16c70 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
16c80 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
16c90 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
16ca0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
16cb0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
16cc0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
16cd0 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
16ce0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
16cf0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16d00 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
16d10 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
16d20 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
16d30 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
16d40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16d50 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
16d60 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
16d70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
16d80 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
16d90 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
16da0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
16db0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16dc0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
16dd0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
16de0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
16df0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
16e00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
16e10 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
16e20 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
16e30 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
16e40 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
16e50 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
16e60 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
16e70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
16e80 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
16e90 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
16ea0 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
16eb0 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
16ec0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
16ed0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
16ee0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16ef0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
16f00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16f10 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
16f20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16f30 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
16f40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16f50 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
16f60 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
16f70 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
16f80 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
16f90 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
16fa0 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
16fb0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
16fc0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
16fd0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
16fe0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
16ff0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17000 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
17010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
17020 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
17030 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
17040 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
17050 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
17060 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
17070 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
17080 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
17090 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
170a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
170b0 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
170c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
170d0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
170e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
170f0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
17100 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
17110 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
17120 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
17130 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
17140 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
17150 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
17160 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
17170 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
17180 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
17190 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
171a0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
171b0 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
171c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
171d0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
171e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
171f0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
17200 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
17210 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
17220 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
17230 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
17240 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
17250 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
17260 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
17270 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
17280 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
17290 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
172a0 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
172b0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
172c0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
172d0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
172e0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
172f0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
17300 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
17310 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
17320 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
17330 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
17340 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
17350 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
17360 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
17370 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
17380 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
17390 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
173a0 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
173b0 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
173c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
173d0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
173e0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
173f0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
17400 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
17410 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
17420 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
17430 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17440 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
17450 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17460 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
17470 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
17480 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
17490 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
174a0 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
174b0 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
174c0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
174d0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
174e0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
174f0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
17500 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
17510 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
17520 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
17530 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
17540 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
17550 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
17560 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
17570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17580 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
17590 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
175a0 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
175b0 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
175c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
175d0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
175e0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
175f0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
17600 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
17610 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
17620 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
17630 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
17640 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
17650 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
17660 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
17670 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
17680 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
17690 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
176a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
176b0 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
176c0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
176d0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
176e0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
176f0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
17700 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
17710 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
17720 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
17730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17740 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
17750 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17760 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17770 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17780 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17790 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
177a0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
177b0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
177c0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
177d0 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
177e0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
177f0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
17800 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
17810 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
17820 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17830 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
17840 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
17850 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
17860 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
17870 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
17880 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
17890 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
178a0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
178b0 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
178c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
178d0 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
178e0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
178f0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
17900 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17910 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
17920 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
17930 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17940 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
17950 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
17960 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
17970 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
17980 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
17990 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
179a0 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
179b0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
179c0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
179d0 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
179e0 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
179f0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
17a00 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
17a10 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
17a20 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
17a30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17a40 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
17a50 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17a60 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
17a70 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17a80 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
17a90 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17aa0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
17ab0 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
17ac0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
17ad0 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
17ae0 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
17af0 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
17b00 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
17b10 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
17b20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
17b30 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
17b40 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
17b50 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
17b60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17b70 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
17b80 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
17b90 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
17ba0 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
17bb0 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
17bc0 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
17bd0 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
17be0 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
17bf0 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
17c00 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
17c10 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
17c20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
17c30 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
17c40 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
17c50 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
17c60 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
17c70 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
17c80 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  lue..**.** [[SQL
17c90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17ca0 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c  RNL_SPILL]].** <
17cb0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17cc0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a  _STMTJRNL_SPILL.
17cd0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17ce0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
17cf0 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20  NL_SPILL option 
17d00 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
17d10 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
17d20 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73  * becomes the [s
17d30 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
17d40 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20  ] spill-to-disk 
17d50 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20  threshold.  .** 
17d60 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [Statement journ
17d70 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e  als] are held in
17d80 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68   memory until th
17d90 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74  eir size (in byt
17da0 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74  es).** exceeds t
17db0 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61  his threshold, a
17dc0 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68  t which point th
17dd0 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74  ey are written t
17de0 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66  o disk..** Or if
17df0 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69   the threshold i
17e00 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20  s -1, statement 
17e10 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77  journals are alw
17e20 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c  ays held.** excl
17e30 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72  usively in memor
17e40 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79  y..** Since many
17e50 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
17e60 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65  als never become
17e70 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20   large, setting 
17e80 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72  the spill.** thr
17e90 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75  eshold to a valu
17ea0 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20  e such as 64KiB 
17eb0 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75  can greatly redu
17ec0 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ce the amount of
17ed0 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64  .** I/O required
17ee0 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74   to support stat
17ef0 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a  ement rollback..
17f00 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
17f10 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65  alue for this se
17f20 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c  tting is control
17f30 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  led by the.** [S
17f40 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53  QLITE_STMTJRNL_S
17f50 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  PILL] compile-ti
17f60 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  me option..**.**
17f70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17f80 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 5d  _SORTERREF_SIZE]
17f90 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17fa0 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46  CONFIG_SORTERREF
17fb0 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65  _SIZE.** <dd>The
17fc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17fd0 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f 70  ORTERREF_SIZE op
17fe0 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73  tion accepts a s
17ff0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a  ingle parameter.
18000 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74 29  ** of type (int)
18010 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75 65   - the new value
18020 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d 72   of the sorter-r
18030 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68  eference size th
18040 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 61  reshold..** Usua
18050 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74 65  lly, when SQLite
18060 20 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e 61   uses an externa
18070 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72 20  l sort to order 
18080 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69 6e  records accordin
18090 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45 52  g.** to an ORDER
180a0 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c 20   BY clause, all 
180b0 66 69 65 6c 64 73 20 72 65 71 75 69 72 65 64 20  fields required 
180c0 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61 72  by the caller ar
180d0 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65  e present in the
180e0 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f 72  .** sorted recor
180f0 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20  ds. However, if 
18100 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
18110 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 64  s based on the d
18120 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a 20  eclared type.** 
18130 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  of a table colum
18140 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c 75 65  n that its value
18150 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
18160 62 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d 20  be very large - 
18170 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20 74  larger.** than t
18180 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73 6f  he configured so
18190 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73  rter-reference s
181a0 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d 20  ize threshold - 
181b0 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63 65  then a reference
181c0 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69 6e  .** is stored in
181d0 20 65 61 63 68 20 73 6f 72 74 65 64 20 72 65 63   each sorted rec
181e0 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65 71 75  ord and the requ
181f0 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ired column valu
18200 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 6f  es loaded.** fro
18210 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  m the database a
18220 73 20 72 65 63 6f 72 64 73 20 61 72 65 20 72 65  s records are re
18230 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65 64  turned in sorted
18240 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66 61   order. The defa
18250 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72  ult.** value for
18260 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
18270 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68 69  to never use thi
18280 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20  s optimization. 
18290 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a 2a  Specifying a .**
182a0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
182b0 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  for this option 
182c0 72 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 66  restores the def
182d0 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e 0a  ault behaviour..
182e0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  ** This option i
182f0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
18300 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
18310 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
18320 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
18330 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45 4e  E_SORTER_REFEREN
18340 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CES] compile-tim
18350 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64  e option..** </d
18360 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18370 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
18380 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
18390 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
183a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
183b0 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
183c0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
183d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
183e0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
183f0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
18400 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18410 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
18420 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
18430 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
18440 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18450 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
18460 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
18470 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
18480 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18490 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
184a0 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72   6  /* No longer
184b0 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
184c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
184d0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
184e0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
184f0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
18500 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18510 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
18520 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
18530 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
18540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18550 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
18560 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
18570 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
18580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
18590 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
185a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
185b0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
185c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
185d0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
185e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
185f0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
18600 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
18610 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
18620 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
18630 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
18640 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
18650 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
18660 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
18670 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18680 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18690 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
186a0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
186b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
186c0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
186d0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
186e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
186f0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
18700 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
18710 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
18720 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
18730 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
18740 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18760 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
18770 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
18780 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
18790 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
187a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
187b0 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
187c0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
187d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
187e0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
187f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
18800 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
18810 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18820 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
18830 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
18840 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
18850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
18860 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
18870 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
18880 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
18890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
188a0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
188b0 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
188c0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
188d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
188e0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
188f0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
18900 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
18910 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18920 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
18930 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
18940 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
18950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18960 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
18970 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36  NL_SPILL      26
18980 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
18990 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
189a0 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41  _CONFIG_SMALL_MA
189b0 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20  LLOC        27  
189c0 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
189d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
189e0 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49  FIG_SORTERREF_SI
189f0 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20 69  ZE      28  /* i
18a00 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a  nt nByte */../*.
18a10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
18a20 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
18a30 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
18a40 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
18a50 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
18a60 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
18a70 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
18a80 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
18a90 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
18aa0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
18ab0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
18ac0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
18ad0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
18ae0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
18af0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18b00 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
18b10 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
18b20 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
18b30 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
18b40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
18b50 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
18b60 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
18b70 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
18b80 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
18b90 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
18ba0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
18bb0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
18bc0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
18bd0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
18be0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
18bf0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
18c00 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
18c10 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
18c20 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
18c30 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
18c40 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
18c50 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
18c60 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
18c70 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
18c80 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18c90 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
18ca0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
18cb0 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
18cc0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
18cd0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
18ce0 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
18cf0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
18d00 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
18d10 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
18d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
18d30 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
18d40 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
18d50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
18d60 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
18d70 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
18d80 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
18d90 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
18da0 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
18db0 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
18dc0 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
18dd0 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
18de0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
18df0 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
18e00 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
18e10 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
18e20 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
18e30 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
18e40 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
18e50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
18e60 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
18e70 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
18e80 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
18e90 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
18ea0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
18eb0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
18ec0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
18ed0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
18ee0 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
18ef0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18f00 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
18f10 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
18f20 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
18f30 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
18f40 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
18f50 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
18f60 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
18f70 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
18f80 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
18f90 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
18fa0 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
18fb0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18fc0 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
18fd0 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
18fe0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
18ff0 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
19000 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
19010 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
19020 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
19030 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
19040 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
19050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19060 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
19070 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
19080 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
19090 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
190a0 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
190b0 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
190c0 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
190d0 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
190e0 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
190f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
19100 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
19110 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
19120 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
19130 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
19140 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
19150 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
19160 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
19170 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
19180 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
19190 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
191a0 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
191b0 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
191c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
191d0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
191e0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
191f0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
19200 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
19210 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
19220 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
19230 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
19240 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
19250 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
19260 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
19270 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
19280 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
19290 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
192a0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
192b0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
192c0 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
192d0 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
192e0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
192f0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
19300 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
19310 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
19320 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
19330 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
19340 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19350 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19360 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19370 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19380 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
19390 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
193a0 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
193b0 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
193c0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
193d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
193e0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
193f0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
19400 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
19410 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
19420 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
19430 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
19440 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
19450 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19460 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
19470 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
19480 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
19490 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
194a0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
194b0 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
194c0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
194d0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
194e0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
194f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19500 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
19510 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
19520 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
19530 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
19540 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
19550 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
19560 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
19570 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
19580 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19590 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
195a0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
195b0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
195c0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
195d0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
195e0 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
195f0 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
19600 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
19610 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
19620 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19630 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
19640 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
19650 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
19660 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
19670 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
19680 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
19690 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
196a0 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f  G_ENABLE_FTS3_TO
196b0 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20  KENIZER</dt>.** 
196c0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
196d0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
196e0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
196f0 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a  he two-argument.
19700 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ** version of th
19710 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  e [fts3_tokenize
19720 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68  r()] function wh
19730 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74  ich is part of t
19740 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c  he.** [FTS3] ful
19750 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e  l-text search en
19760 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a  gine extension..
19770 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
19780 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
19790 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
197a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
197b0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
197c0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
197d0 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65  isable fts3_toke
197e0 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f  nizer() or.** po
197f0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
19800 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28   fts3_tokenizer(
19810 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  ) or negative to
19820 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
19830 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  ng.** unchanged.
19840 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
19850 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19860 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19870 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19880 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19890 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
198a0 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b  whether fts3_tok
198b0 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  enizer is disabl
198c0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
198d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
198e0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
198f0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
19900 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
19910 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
19920 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
19930 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
19940 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
19950 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
19960 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19970 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c  _LOAD_EXTENSION<
19980 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
19990 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
199a0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
199b0 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69  isable the [sqli
199c0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
199d0 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  on()].** interfa
199e0 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79  ce independently
199f0 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78   of the [load_ex
19a00 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66  tension()] SQL f
19a10 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
19a20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
19a30 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
19a40 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72  ] API enables or
19a50 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74   disables both t
19a60 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c  he.** C-API [sql
19a70 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
19a80 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53  ion()] and the S
19a90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61  QL function [loa
19aa0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  d_extension()]..
19ab0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
19ac0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
19ad0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
19ae0 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61  When the first a
19af0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
19b00 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20  interface is 1, 
19b10 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d  then only the C-
19b20 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65  API is.** enable
19b30 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  d and the SQL fu
19b40 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64  nction remains d
19b50 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65  isabled.  If the
19b60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19b70 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  to.** this inter
19b80 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20  face is 0, then 
19b90 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61  both the C-API a
19ba0 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
19bb0 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64  ion are disabled
19bc0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73  ..** If the firs
19bd0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31  t argument is -1
19be0 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  , then no change
19bf0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74  s are made to st
19c00 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68  ate of either th
19c10 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68  e.** C-API or th
19c20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  e SQL function..
19c30 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
19c40 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
19c50 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
19c60 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
19c70 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
19c80 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19c90 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  hether [sqlite3_
19ca0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
19cb0 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
19cc0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
19cd0 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  abled following 
19ce0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
19cf0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19d00 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c   may.** be a NUL
19d10 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68  L pointer, in wh
19d20 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
19d30 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
19d40 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a  reported back..*
19d50 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
19d60 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
19d70 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74  G_MAINDBNAME</dt
19d80 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
19d90 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
19da0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d  o change the nam
19db0 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20  e of the "main" 
19dc0 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65  database.** sche
19dd0 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61  ma.  ^The sole a
19de0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
19df0 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61  nter to a consta
19e00 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a  nt UTF8 string.*
19e10 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63  * which will bec
19e20 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65  ome the new sche
19e30 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65  ma name in place
19e40 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51   of "main".  ^SQ
19e50 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
19e60 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
19e70 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68  the new main sch
19e80 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c  ema name string,
19e90 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   so the applicat
19ea0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
19eb0 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75  re that the argu
19ec0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f  ment passed into
19ed0 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f   this DBCONFIG o
19ee0 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67  ption is unchang
19ef0 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65  ed.** until afte
19f00 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
19f10 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
19f20 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
19f30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19f40 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f  NFIG_NO_CKPT_ON_
19f50 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CLOSE</dt>.** <d
19f60 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e  d> Usually, when
19f70 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77   a database in w
19f80 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65  al mode is close
19f90 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72  d or detached fr
19fa0 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73  om a .** databas
19fb0 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65  e handle, SQLite
19fc0 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20   checks if this 
19fd0 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74  will mean that t
19fe0 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20  here are now no 
19ff0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  .** connections 
1a000 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61  at all to the da
1a010 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69  tabase. If so, i
1a020 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65  t performs a che
1a030 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72  ckpoint .** oper
1a040 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f  ation before clo
1a050 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74  sing the connect
1a060 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e  ion. This option
1a070 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a   may be used to.
1a080 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73  ** override this
1a090 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20   behaviour. The 
1a0a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1a0b0 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f  passed to this o
1a0c0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61  peration.** is a
1a0d0 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f 73 69  n integer - posi
1a0e0 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c 65 20  tive to disable 
1a0f0 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63  checkpoints-on-c
1a100 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74  lose, or zero (t
1a110 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74  he.** default) t
1a120 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20 61  o enable them, a
1a130 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  nd negative to l
1a140 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
1a150 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
1a160 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a170 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1a180 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   to an integer.*
1a190 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20  * into which is 
1a1a0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
1a1b0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1a1c0 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  er checkpoints-o
1a1d0 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20  n-close.** have 
1a1e0 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20  been disabled - 
1a1f0 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f  0 if they are no
1a200 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66  t disabled, 1 if
1a210 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f   they are..** </
1a220 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1a230 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1a240 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a  ABLE_QPSG</dt>.*
1a250 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
1a260 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1a270 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61  LE_QPSG option a
1a280 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63  ctivates or deac
1a290 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b  tivates.** the [
1a2a0 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74  query planner st
1a2b0 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65  ability guarante
1a2c0 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e  e] (QPSG).  When
1a2d0 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63 74   the QPSG is act
1a2e0 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  ive,.** a single
1a2f0 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74 65   SQL query state
1a300 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73  ment will always
1a310 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c   use the same al
1a320 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65  gorithm regardle
1a330 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20  ss.** of values 
1a340 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
1a350 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53  ters].)^ The QPS
1a360 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20  G disables some 
1a370 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69  query optimizati
1a380 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b  ons.** that look
1a390 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f   at the values o
1a3a0 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  f bound paramete
1a3b0 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61  rs, which can ma
1a3c0 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a  ke some queries.
1a3d0 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20  ** slower.  But 
1a3e0 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68 65  the QPSG has the
1a3f0 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f   advantage of mo
1a400 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20 62  re predictable b
1a410 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a  ehavior.  With.*
1a420 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69 76  * the QPSG activ
1a430 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  e, SQLite will a
1a440 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61  lways use the sa
1a450 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e  me query plan in
1a460 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a   the field as.**
1a470 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e 67   was used during
1a480 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20   testing in the 
1a490 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  lab..** The firs
1a4a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1a4b0 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 61 6e  is setting is an
1a4c0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
1a4d0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 0a  s 0 to disable .
1a4e0 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70 6f 73  ** the QPSG, pos
1a4f0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
1a500 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69 76  QPSG, or negativ
1a510 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
1a520 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e  etting.** unchan
1a530 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ged. The second 
1a540 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1a550 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
1a560 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
1a570 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
1a580 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
1a590 20 77 68 65 74 68 65 72 20 74 68 65 20 51 50 53   whether the QPS
1a5a0 47 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  G is disabled or
1a5b0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
1a5c0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
1a5d0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1a5e0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1a5f0 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 3c  FIG_TRIGGER_EQP<
1a600 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20  /dt>.** <dd> By 
1a610 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74  default, the out
1a620 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51  put of EXPLAIN Q
1a630 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e  UERY PLAN comman
1a640 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20  ds does not .** 
1a650 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66  include output f
1a660 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e  or any operation
1a670 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  s performed by t
1a680 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e  rigger programs.
1a690 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20   This.** option 
1a6a0 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
1a6b0 72 20 63 6c 65 61 72 20 28 74 68 65 20 64 65 66  r clear (the def
1a6c0 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61  ault) a flag tha
1a6d0 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a  t governs this.*
1a6e0 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20  * behavior. The 
1a6f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1a700 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f  passed to this o
1a710 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69  peration is an i
1a720 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73 69  nteger -.** posi
1a730 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 6f  tive to enable o
1a740 75 74 70 75 74 20 66 6f 72 20 74 72 69 67 67 65  utput for trigge
1a750 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a  r programs, or z
1a760 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69  ero to disable i
1a770 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69 76  t,.** or negativ
1a780 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
1a790 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
1a7a0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1a7b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1a7c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
1a7d0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20  eger into which 
1a7e0 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30  is written .** 0
1a7f0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
1a800 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75 74  e whether output
1a810 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61  -for-triggers ha
1a820 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20  s been disabled 
1a830 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73  - 0 if .** it is
1a840 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
1a850 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20   if it is.  .** 
1a860 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1a870 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a880 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 3c 2f  RESET_DATABASE</
1a890 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53 65 74 20  dt>.** <dd> Set 
1a8a0 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
1a8b0 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41  FIG_RESET_DATABA
1a8c0 53 45 20 66 6c 61 67 20 61 6e 64 20 74 68 65 6e  SE flag and then
1a8d0 20 72 75 6e 0a 2a 2a 20 5b 56 41 43 55 55 4d 5d   run.** [VACUUM]
1a8e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 73   in order to res
1a8f0 65 74 20 61 20 64 61 74 61 62 61 73 65 20 62 61  et a database ba
1a900 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 64  ck to an empty d
1a910 61 74 61 62 61 73 65 0a 2a 2a 20 77 69 74 68 20  atabase.** with 
1a920 6e 6f 20 73 63 68 65 6d 61 20 61 6e 64 20 6e 6f  no schema and no
1a930 20 63 6f 6e 74 65 6e 74 2e 20 54 68 65 20 66 6f   content. The fo
1a940 6c 6c 6f 77 69 6e 67 20 70 72 6f 63 65 73 73 20  llowing process 
1a950 77 6f 72 6b 73 20 65 76 65 6e 20 66 6f 72 0a 2a  works even for.*
1a960 2a 20 61 20 62 61 64 6c 79 20 63 6f 72 72 75 70  * a badly corrup
1a970 74 65 64 20 64 61 74 61 62 61 73 65 20 66 69 6c  ted database fil
1a980 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  e:.** <ol>.** <l
1a990 69 3e 20 49 66 20 74 68 65 20 64 61 74 61 62 61  i> If the databa
1a9a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1a9b0 20 6e 65 77 6c 79 20 6f 70 65 6e 65 64 2c 20 6d   newly opened, m
1a9c0 61 6b 65 20 73 75 72 65 20 69 74 20 68 61 73 20  ake sure it has 
1a9d0 72 65 61 64 20 74 68 65 0a 2a 2a 20 20 20 20 20  read the.**     
1a9e0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
1a9f0 20 62 79 20 70 72 65 70 61 72 69 6e 67 20 74 68   by preparing th
1aa00 65 6e 20 64 69 73 63 61 72 64 69 6e 67 20 73 6f  en discarding so
1aa10 6d 65 20 71 75 65 72 79 20 61 67 61 69 6e 73 74  me query against
1aa20 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 64 61 74   the.**      dat
1aa30 61 62 61 73 65 2c 20 6f 72 20 63 61 6c 6c 69 6e  abase, or callin
1aa40 67 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  g sqlite3_table_
1aa50 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
1aa60 29 2c 20 69 67 6e 6f 72 69 6e 67 20 61 6e 79 0a  ), ignoring any.
1aa70 2a 2a 20 20 20 20 20 20 65 72 72 6f 72 73 2e 20  **      errors. 
1aa80 20 54 68 69 73 20 73 74 65 70 20 69 73 20 6f 6e   This step is on
1aa90 6c 79 20 6e 65 63 65 73 73 61 72 79 20 69 66 20  ly necessary if 
1aaa0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1aab0 64 65 73 69 72 65 73 20 74 6f 20 6b 65 65 70 0a  desires to keep.
1aac0 2a 2a 20 20 20 20 20 20 74 68 65 20 64 61 74 61  **      the data
1aad0 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f 64 65  base in WAL mode
1aae0 20 61 66 74 65 72 20 74 68 65 20 72 65 73 65 74   after the reset
1aaf0 20 69 66 20 69 74 20 77 61 73 20 69 6e 20 57 41   if it was in WA
1ab00 4c 20 6d 6f 64 65 20 62 65 66 6f 72 65 0a 2a 2a  L mode before.**
1ab10 20 20 20 20 20 20 74 68 65 20 72 65 73 65 74 2e        the reset.
1ab20 20 20 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74    .** <li> sqlit
1ab30 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c  e3_db_config(db,
1ab40 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1ab50 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c  _RESET_DATABASE,
1ab60 20 31 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20   1, 0);.** <li> 
1ab70 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 5d 28 64  [sqlite3_exec](d
1ab80 62 2c 20 22 5b 56 41 43 55 55 4d 5d 22 2c 20 30  b, "[VACUUM]", 0
1ab90 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e  , 0, 0);.** <li>
1aba0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
1abb0 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42  ig(db, SQLITE_DB
1abc0 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1abd0 41 42 41 53 45 2c 20 30 2c 20 30 29 3b 0a 2a 2a  ABASE, 0, 0);.**
1abe0 20 3c 2f 6f 6c 3e 0a 2a 2a 20 42 65 63 61 75 73   </ol>.** Becaus
1abf0 65 20 72 65 73 65 74 74 69 6e 67 20 61 20 64 61  e resetting a da
1ac00 74 61 62 61 73 65 20 69 73 20 64 65 73 74 72 75  tabase is destru
1ac10 63 74 69 76 65 20 61 6e 64 20 69 72 72 65 76 65  ctive and irreve
1ac20 72 73 69 62 6c 65 2c 20 74 68 65 0a 2a 2a 20 70  rsible, the.** p
1ac30 72 6f 63 65 73 73 20 72 65 71 75 69 72 65 73 20  rocess requires 
1ac40 74 68 65 20 75 73 65 20 6f 66 20 74 68 69 73 20  the use of this 
1ac50 6f 62 73 63 75 72 65 20 41 50 49 20 61 6e 64 20  obscure API and 
1ac60 6d 75 6c 74 69 70 6c 65 20 73 74 65 70 73 20 74  multiple steps t
1ac70 6f 20 68 65 6c 70 0a 2a 2a 20 65 6e 73 75 72 65  o help.** ensure
1ac80 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
1ac90 74 20 68 61 70 70 65 6e 20 62 79 20 61 63 63 69  t happen by acci
1aca0 64 65 6e 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  dent..** </dd>.*
1acb0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
1acc0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1acd0 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20  IG_MAINDBNAME   
1ace0 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a           1000 /*
1acf0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a   const char* */.
1ad00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ad10 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
1ad20 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30  E             10
1ad30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  01 /* void* int 
1ad40 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
1ad50 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1ad60 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20  NABLE_FKEY      
1ad70 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74       1002 /* int
1ad80 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1ad90 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1ada0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
1adb0 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69         1003 /* i
1adc0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1add0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1ade0 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
1adf0 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a  OKENIZER 1004 /*
1ae00 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1ae10 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1ae20 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
1ae30 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20  _EXTENSION 1005 
1ae40 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1ae50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1ae60 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f  CONFIG_NO_CKPT_O
1ae70 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30  N_CLOSE      100
1ae80 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  6 /* int int* */
1ae90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1aea0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1aeb0 51 50 53 47 20 20 20 20 20 20 20 20 20 20 20 31  QPSG           1
1aec0 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  007 /* int int* 
1aed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1aee0 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47  E_DBCONFIG_TRIGG
1aef0 45 52 5f 45 51 50 20 20 20 20 20 20 20 20 20 20  ER_EQP          
1af00 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 69 6e 74   1008 /* int int
1af10 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1af20 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1af30 45 54 5f 44 41 54 41 42 41 53 45 20 20 20 20 20  ET_DATABASE     
1af40 20 20 20 31 30 30 39 20 2f 2a 20 69 6e 74 20 69     1009 /* int i
1af50 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1af60 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
1af70 41 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AX              
1af80 20 20 20 20 20 31 30 30 39 20 2f 2a 20 4c 61 72       1009 /* Lar
1af90 67 65 73 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f  gest DBCONFIG */
1afa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1afb0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
1afc0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
1afd0 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54  ult Codes.** MET
1afe0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1aff0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b000 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
1b010 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
1b020 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
1b030 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
1b040 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1b050 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
1b060 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
1b070 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
1b080 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
1b090 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
1b0a0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
1b0b0 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
1b0c0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1b0d0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
1b0e0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
1b0f0 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
1b100 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
1b110 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f  t Rowid.** METHO
1b120 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1b130 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
1b140 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
1b150 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
1b160 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
1b170 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
1b180 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
1b190 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
1b1a0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
1b1b0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
1b1c0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
1b1d0 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
1b1e0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
1b1f0 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
1b200 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
1b210 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
1b220 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
1b230 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
1b240 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
1b250 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
1b260 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
1b270 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
1b280 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
1b290 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
1b2a0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
1b2b0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
1b2c0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
1b2d0 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
1b2e0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1b2f0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
1b300 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72  erface usually r
1b310 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
1b320 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73  d] of.** the mos
1b330 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
1b340 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
1b350 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
1b360 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
1b370 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
1b380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
1b390 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
1b3a0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
1b3b0 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  bles are not.** 
1b3c0 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f  recorded. ^If no
1b3d0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1b3e0 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
1b3f0 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65   tables have eve
1b400 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f  r occurred .** o
1b410 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1b420 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65  onnection D, the
1b430 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
1b440 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
1b450 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e  eturns .** zero.
1b460 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61  .**.** As well a
1b470 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f  s being set auto
1b480 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77  matically as row
1b490 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69  s are inserted i
1b4a0 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  nto database.** 
1b4b0 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75  tables, the valu
1b4c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
1b4d0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
1b4e0 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c  be set explicitl
1b4f0 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  y by.** [sqlite3
1b500 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1b510 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20  _rowid()].**.** 
1b520 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62  Some virtual tab
1b530 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1b540 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f  ns may INSERT ro
1b550 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ws into rowid ta
1b560 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20  bles as.** part 
1b570 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20  of committing a 
1b580 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67  transaction (e.g
1b590 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  . to flush data 
1b5a0 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d  accumulated in m
1b5b0 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b  emory.** to disk
1b5c0 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20  ). In this case 
1b5d0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1b5e0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
1b5f0 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77  n return the row
1b600 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  id.** associated
1b610 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65   with these inte
1b620 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72  rnal INSERT oper
1b630 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65  ations, which le
1b640 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74  ads to .** unint
1b650 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20  uitive results. 
1b660 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
1b670 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68  plementations th
1b680 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72  at do write to r
1b690 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69  owid.** tables i
1b6a0 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61  n this way can a
1b6b0 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65  void this proble
1b6c0 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74  m by restoring t
1b6d0 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20  he original .** 
1b6e0 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e  rowid value usin
1b6f0 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  g [sqlite3_set_l
1b700 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1b710 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72  ()] before retur
1b720 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c  ning .** control
1b730 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a   to the user..**
1b740 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
1b750 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
1b760 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65  in a trigger the
1b770 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
1b780 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ill .** return t
1b790 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
1b7a0 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61  e inserted row a
1b7b0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
1b7c0 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e  igger is .** run
1b7d0 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74  ning. Once the t
1b7e0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
1b7f0 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
1b800 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
1b810 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
1b820 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
1b830 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
1b840 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e  igger was fired.
1b850 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
1b860 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
1b870 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
1b880 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
1b890 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
1b8a0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
1b8b0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
1b8c0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
1b8d0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
1b8e0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
1b8f0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
1b900 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
1b910 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
1b920 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
1b930 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
1b940 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
1b950 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1b960 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
1b970 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
1b980 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
1b990 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
1b9a0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
1b9b0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
1b9c0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
1b9d0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
1b9e0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
1b9f0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
1ba00 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
1ba10 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
1ba20 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
1ba30 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
1ba40 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
1ba50 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
1ba60 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
1ba70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1ba80 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1ba90 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
1baa0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
1bab0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
1bac0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
1bad0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
1bae0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
1baf0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
1bb00 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
1bb10 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
1bb20 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
1bb30 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
1bb40 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
1bb50 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
1bb60 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
1bb70 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1bb80 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1bb90 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
1bba0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
1bbb0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
1bbc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
1bbd0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
1bbe0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1bbf0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
1bc00 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
1bc10 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
1bc20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1bc30 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
1bc40 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1bc50 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
1bc60 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1bc70 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
1bc80 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
1bc90 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
1bca0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
1bcb0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
1bcc0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
1bcd0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1bce0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1bcf0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
1bd00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bd10 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20  F: Set the Last 
1bd20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c  Insert Rowid val
1bd30 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ue..** METHOD: s
1bd40 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
1bd50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73   sqlite3_set_las
1bd60 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1bd70 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f  , R) method allo
1bd80 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ws the applicati
1bd90 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65  on to.** set the
1bda0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1bdb0 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  by calling sqlit
1bdc0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1bdd0 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a  owid(D) to R .**
1bde0 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69   without inserti
1bdf0 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68  ng a row into th
1be00 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76  e database..*/.v
1be10 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
1be20 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1be30 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74  d(sqlite3*,sqlit
1be40 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
1be50 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
1be60 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
1be70 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1be80 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1be90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1bea0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1beb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1bec0 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
1bed0 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
1bee0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
1bef0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
1bf00 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1bf10 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
1bf20 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
1bf30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bf40 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
1bf50 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1bf60 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
1bf70 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1bf80 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1bf90 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
1bfa0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1bfb0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
1bfc0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
1bfd0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1bfe0 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
1bff0 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
1c000 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1c010 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
1c020 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
1c030 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
1c040 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
1c050 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
1c060 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
1c070 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
1c080 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
1c090 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1c0a0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1c0b0 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
1c0c0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1c0d0 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
1c0e0 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
1c0f0 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
1c100 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
1c110 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1c120 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
1c130 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1c140 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
1c150 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
1c160 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1c170 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
1c180 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
1c190 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
1c1a0 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
1c1b0 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
1c1c0 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
1c1d0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
1c1e0 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
1c1f0 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
1c200 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1c210 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1c220 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
1c230 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
1c240 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
1c250 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
1c260 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
1c270 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
1c280 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1c290 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
1c2a0 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
1c2b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
1c2c0 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
1c2d0 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
1c2e0 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
1c2f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1c300 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
1c310 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
1c320 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
1c330 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1c340 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
1c350 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1c360 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
1c370 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
1c380 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
1c390 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
1c3a0 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
1c3b0 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
1c3c0 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
1c3d0 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
1c3e0 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
1c3f0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
1c400 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
1c410 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
1c420 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
1c430 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1c440 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1c450 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
1c460 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
1c470 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
1c480 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
1c490 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
1c4a0 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
1c4b0 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
1c4c0 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
1c4d0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1c4e0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
1c4f0 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
1c500 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
1c510 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
1c520 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
1c530 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
1c540 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
1c550 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
1c560 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
1c570 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
1c580 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
1c590 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
1c5a0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1c5b0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1c5c0 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
1c5d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1c5e0 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
1c5f0 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
1c600 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
1c610 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
1c620 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
1c630 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
1c640 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
1c650 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1c660 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
1c670 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1c680 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
1c690 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1c6a0 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
1c6b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
1c6c0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1c6d0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1c6e0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
1c6f0 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  trigger..**.** I
1c700 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1c710 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1c720 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1c730 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c740 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1c750 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1c760 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1c770 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1c780 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
1c790 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1c7a0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20  aningful..**.** 
1c7b0 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c  See also:.** <ul
1c7c0 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73  >.** <li> the [s
1c7d0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1c7e0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1c7f0 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63  e.** <li> the [c
1c800 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1c810 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65  gma].** <li> the
1c820 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1c830 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69  function].** <li
1c840 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73  > the [data_vers
1c850 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c  ion pragma].** <
1c860 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ul>.*/.int sqli
1c870 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
1c880 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1c890 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
1c8a0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
1c8b0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
1c8c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1c8d0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
1c8e0 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20  turns the total 
1c8f0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
1c900 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65  nserted, modifie
1c910 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d or.** deleted 
1c920 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c  by all [INSERT],
1c930 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
1c940 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
1c950 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69   completed.** si
1c960 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nce the database
1c970 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20   connection was 
1c980 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e  opened, includin
1c990 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64  g those executed
1c9a0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74   as.** part of t
1c9b0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e  rigger programs.
1c9c0 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
1c9d0 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
1c9e0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64  L statement.** d
1c9f0 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74  oes not affect t
1ca00 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1ca10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
1ca20 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a  al_changes()..**
1ca30 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61   .** ^Changes ma
1ca40 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66  de as part of [f
1ca50 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
1ca60 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64  ns] are included
1ca70 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74   in the.** count
1ca80 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65  , but those made
1ca90 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c   as part of REPL
1caa0 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  ACE constraint r
1cab0 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a  esolution are.**
1cac0 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74   not. ^Changes t
1cad0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1cae0 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
1caf0 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
1cb00 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74  gers .** are not
1cb10 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
1cb20 54 68 69 73 20 74 68 65 20 5b 73 71 6c 69 74 65  This the [sqlite
1cb30 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1cb40 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  D)] interface on
1cb50 6c 79 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e  ly reports the n
1cb60 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 72 6f 77 73  umber.** of rows
1cb70 20 74 68 61 74 20 63 68 61 6e 67 65 64 20 64 75   that changed du
1cb80 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
1cb90 6e 74 20 72 75 6e 20 61 67 61 69 6e 73 74 20 64  nt run against d
1cba0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
1cbb0 63 74 69 6f 6e 20 44 2e 20 20 41 6e 79 20 63 68  ction D.  Any ch
1cbc0 61 6e 67 65 73 20 62 79 20 6f 74 68 65 72 20 64  anges by other d
1cbd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cbe0 6f 6e 73 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  ons are ignored.
1cbf0 0a 2a 2a 20 54 6f 20 64 65 74 65 63 74 20 63 68  .** To detect ch
1cc00 61 6e 67 65 73 20 61 67 61 69 6e 73 74 20 61 20  anges against a 
1cc10 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 66 72  database file fr
1cc20 6f 6d 20 6f 74 68 65 72 20 64 61 74 61 62 61 73  om other databas
1cc30 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  e.** connections
1cc40 20 75 73 65 20 74 68 65 20 5b 50 52 41 47 4d 41   use the [PRAGMA
1cc50 20 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d 20 63   data_version] c
1cc60 6f 6d 6d 61 6e 64 20 6f 72 20 74 68 65 0a 2a 2a  ommand or the.**
1cc70 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44   [SQLITE_FCNTL_D
1cc80 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b 66 69  ATA_VERSION] [fi
1cc90 6c 65 20 63 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20  le control]..** 
1cca0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1ccb0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1ccc0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1ccd0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1cce0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1ccf0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1cd00 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1cd10 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1cd20 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1cd30 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1cd40 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1cd50 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ful..**.** See a
1cd60 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  lso:.** <ul>.** 
1cd70 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69 74 65  <li> the [sqlite
1cd80 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
1cd90 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74  erface.** <li> t
1cda0 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  he [count_change
1cdb0 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69  s pragma].** <li
1cdc0 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  > the [changes()
1cdd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a   SQL function].*
1cde0 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74 61  * <li> the [data
1cdf0 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61 5d  _version pragma]
1ce00 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 53 51  .** <li> the [SQ
1ce10 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f  LITE_FCNTL_DATA_
1ce20 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63  VERSION] [file c
1ce30 6f 6e 74 72 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ontrol].** </ul>
1ce40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ce50 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
1ce60 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1ce70 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
1ce80 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
1ce90 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
1cea0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1ceb0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1cec0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1ced0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1cee0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1cef0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1cf00 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1cf10 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1cf20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1cf30 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1cf40 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1cf50 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1cf60 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1cf70 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1cf80 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1cf90 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1cfa0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1cfb0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1cfc0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1cfd0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1cfe0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1cff0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1d000 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1d010 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1d020 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1d030 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1d040 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1d050 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1d060 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1d070 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1d080 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d090 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1d0a0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1d0b0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1d0c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1d0d0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1d0e0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1d0f0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1d100 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1d110 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1d120 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1d130 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1d140 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1d150 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1d160 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1d170 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1d180 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1d190 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1d1a0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1d1b0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1d1c0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1d1d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1d1e0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1d1f0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1d200 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1d210 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1d220 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1d230 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1d240 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1d250 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1d260 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1d270 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1d280 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1d290 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1d2a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1d2b0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1d2c0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1d2d0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1d2e0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1d2f0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1d300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d310 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1d320 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1d330 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1d340 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1d350 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1d360 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1d370 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1d380 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1d390 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1d3a0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1d3b0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1d3c0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1d3d0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1d3e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1d3f0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1d400 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1d410 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1d420 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1d430 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1d440 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1d450 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1d460 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1d470 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1d480 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1d490 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1d4a0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1d4b0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1d4c0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1d4d0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1d4e0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1d4f0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1d500 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1d510 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1d520 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1d530 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1d540 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69   returns..*/.voi
1d550 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
1d560 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
1d570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d580 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
1d590 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
1d5a0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
1d5b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1d5c0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
1d5d0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
1d5e0 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
1d5f0 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
1d600 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
1d610 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
1d620 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1d630 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
1d640 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
1d650 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
1d660 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
1d670 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
1d680 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
1d690 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
1d6a0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
1d6b0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
1d6c0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
1d6d0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1d6e0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
1d6f0 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
1d700 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
1d710 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
1d720 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
1d730 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
1d740 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
1d750 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
1d760 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
1d770 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
1d780 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
1d790 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
1d7a0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
1d7b0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
1d7c0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
1d7d0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
1d7e0 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
1d7f0 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
1d800 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
1d810 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
1d820 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
1d830 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
1d840 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
1d850 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
1d860 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
1d870 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
1d880 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
1d890 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
1d8a0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
1d8b0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1d8c0 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
1d8d0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
1d8e0 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
1d8f0 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
1d900 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
1d910 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
1d920 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1d930 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1d940 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
1d950 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1d960 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
1d970 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
1d980 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
1d990 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
1d9a0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
1d9b0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
1d9c0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1d9d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
1d9e0 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
1d9f0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
1da00 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
1da10 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1da20 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
1da30 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1da40 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
1da50 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
1da60 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
1da70 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
1da80 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1da90 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
1daa0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
1dab0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
1dac0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1dad0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1dae0 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
1daf0 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
1db00 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1db10 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
1db20 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1db30 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1db40 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1db50 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1db60 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1db70 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
1db80 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1db90 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
1dba0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
1dbb0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
1dbc0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1dbd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
1dbe0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
1dbf0 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
1dc00 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
1dc10 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
1dc20 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
1dc30 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
1dc40 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
1dc50 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
1dc60 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1dc70 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
1dc80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1dc90 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
1dca0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1dcb0 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
1dcc0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
1dcd0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
1dce0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1dcf0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
1dd00 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
1dd10 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1dd20 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1dd30 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1dd40 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1dd50 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1dd60 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
1dd70 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
1dd80 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
1dd90 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
1dda0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1ddb0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1ddc0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
1ddd0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1dde0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
1ddf0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
1de00 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1de10 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
1de20 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1de30 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
1de40 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1de50 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1de60 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
1de70 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
1de80 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
1de90 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
1dea0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1deb0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1dec0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1ded0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
1dee0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1def0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1df00 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
1df10 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
1df20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
1df30 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
1df40 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1df50 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
1df60 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
1df70 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1df80 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
1df90 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1dfa0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
1dfb0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
1dfc0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
1dfd0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
1dfe0 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f  ed previously fo
1dff0 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
1e000 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1e010 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1e020 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1e030 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1e040 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1e050 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1e060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1e070 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1e080 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
1e090 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1e0a0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
1e0b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1e0c0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1e0d0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1e0e0 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1e0f0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1e100 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
1e110 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
1e120 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
1e130 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
1e140 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
1e150 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
1e160 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
1e170 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
1e180 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
1e190 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
1e1a0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
1e1b0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
1e1c0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
1e1d0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
1e1e0 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
1e1f0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
1e200 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
1e210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
1e220 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
1e230 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
1e240 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
1e250 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
1e260 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
1e270 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
1e280 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
1e290 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
1e2a0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
1e2b0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
1e2c0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
1e2d0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1e2e0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
1e2f0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
1e300 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
1e310 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
1e320 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
1e330 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
1e340 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
1e350 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1e360 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
1e370 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1e380 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
1e390 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
1e3a0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1e3b0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
1e3c0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
1e3d0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
1e3e0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
1e3f0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
1e400 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
1e410 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
1e420 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
1e430 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
1e440 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
1e450 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
1e460 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
1e470 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
1e480 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
1e490 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
1e4a0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
1e4b0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
1e4c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
1e4d0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
1e4e0 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
1e4f0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1e500 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1e510 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
1e520 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
1e530 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1e540 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
1e550 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
1e560 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
1e570 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
1e580 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
1e590 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
1e5a0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1e5b0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
1e5c0 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
1e5d0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
1e5e0 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
1e5f0 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
1e600 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
1e610 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1e620 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
1e630 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
1e640 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1e650 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
1e660 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
1e670 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
1e680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1e690 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1e6a0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
1e6b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
1e6c0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1e6d0 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
1e6e0 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
1e6f0 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
1e700 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
1e710 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
1e720 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
1e730 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
1e740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e750 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
1e760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1e770 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1e780 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
1e790 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
1e7a0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
1e7b0 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  3*,int(*)(void*,
1e7c0 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  int),void*);../*
1e7d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1e7e0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1e7f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1e800 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1e810 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
1e820 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1e830 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
1e840 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
1e850 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
1e860 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
1e870 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
1e880 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
1e890 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
1e8a0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
1e8b0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
1e8c0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1e8d0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1e8e0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
1e8f0 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
1e900 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1e910 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1e920 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
1e930 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
1e940 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
1e950 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
1e960 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
1e970 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
1e980 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
1e990 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1e9a0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1e9b0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1e9c0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
1e9d0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
1e9e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
1e9f0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1ea00 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1ea10 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
1ea20 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1ea30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
1ea40 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1ea50 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1ea60 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1ea70 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1ea80 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1ea90 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1eaa0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1eab0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1eac0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1ead0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1eae0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1eaf0 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
1eb00 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
1eb10 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1eb20 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1eb30 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1eb40 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1eb50 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1eb60 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1eb70 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ies.** METHOD: s
1eb80 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69  qlite3.**.** Thi
1eb90 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1eba0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1ebb0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1ebc0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1ebd0 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1ebe0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1ebf0 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1ec00 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1ec10 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1ec20 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1ec30 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1ec40 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1ec50 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1ec60 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1ec70 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1ec80 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1ec90 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1eca0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1ecb0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1ecc0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1ecd0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1ece0 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1ecf0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1ed00 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1ed10 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1ed20 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1ed30 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1ed40 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1ed50 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1ed60 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1ed70 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1ed80 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1ed90 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1eda0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1edb0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1edc0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1edd0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1ede0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1edf0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1ee00 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1ee10 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1ee20 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1ee30 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1ee40 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1ee50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1ee60 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1ee70 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1ee80 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1ee90 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1eea0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1eeb0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1eec0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1eed0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1eee0 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1eef0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1ef00 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1ef10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1ef20 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1ef30 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1ef40 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1ef50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1ef60 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1ef70 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1ef80 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1ef90 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1efa0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1efb0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1efc0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1efd0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1efe0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1eff0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1f000 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1f010 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1f020 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1f030 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1f040 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1f050 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1f060 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1f070 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1f080 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1f090 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1f0a0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1f0b0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1f0c0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1f0d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1f0e0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1f0f0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1f100 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1f110 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1f120 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1f130 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1f140 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1f150 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1f160 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1f170 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1f180 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1f190 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1f1a0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1f1b0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1f1c0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1f1d0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1f1e0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1f1f0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1f200 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1f210 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1f220 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1f230 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1f240 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1f250 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1f260 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1f270 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1f280 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1f290 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1f2a0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1f2b0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1f2c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1f2d0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1f2e0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1f2f0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1f300 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1f310 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1f320 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1f330 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1f340 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1f350 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1f360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f370 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1f380 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1f390 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1f3a0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1f3b0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1f3c0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1f3d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1f3e0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1f3f0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1f400 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1f410 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1f420 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1f430 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1f440 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1f450 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1f460 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1f470 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1f480 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1f490 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1f4a0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1f4b0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1f4c0 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1f4d0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1f4e0 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1f4f0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1f500 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1f510 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1f520 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1f530 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1f540 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1f550 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1f560 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1f570 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1f580 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1f590 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1f5a0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1f5b0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1f5c0 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1f5d0 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1f5e0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1f5f0 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1f600 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1f610 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1f620 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1f630 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1f640 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1f650 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1f660 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1f670 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1f680 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1f690 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1f6a0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1f6b0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1f6c0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1f6d0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1f6e0 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1f6f0 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1f700 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1f710 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1f720 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1f730 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1f740 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1f750 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1f760 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1f770 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1f780 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1f790 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f7a0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1f7b0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1f7c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1f7d0 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
1f7e0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1f7f0 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
1f800 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
1f810 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
1f820 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
1f830 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
1f840 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
1f850 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
1f860 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
1f870 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
1f880 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1f890 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
1f8a0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
1f8b0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
1f8c0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1f8d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
1f8e0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1f8f0 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
1f900 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
1f910 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
1f920 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
1f930 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1f940 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
1f950 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f960 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
1f970 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
1f980 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1f990 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
1f9a0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
1f9b0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
1f9c0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
1f9d0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
1f9e0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
1f9f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1fa00 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73  s understand mos
1fa10 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20  t of the common 
1fa20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1fa30 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  ns from.** the s
1fa40 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20  tandard library 
1fa50 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75  printf() .** plu
1fa60 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1fa70 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1fa80 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25  ormats ([%q], [%
1fa90 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25  Q], [%w], and [%
1faa0 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20  z])..** See the 
1fab0 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66  [built-in printf
1fac0 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
1fad0 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a  n for details..*
1fae0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1faf0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1fb00 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1fb10 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1fb20 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1fb30 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1fb40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1fb50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1fb60 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1fb70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1fb80 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1fb90 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1fba0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1fbb0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1fbc0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1fbd0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1fbe0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1fbf0 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20  _malloc64()] is 
1fc00 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1fc10 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1fc20 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1fc30 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1fc40 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1fc50 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1fc60 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1fc70 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1fc80 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1fc90 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1fca0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1fcb0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1fcc0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1fcd0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1fce0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1fcf0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1fd00 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1fd10 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1fd20 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1fd30 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1fd40 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1fd50 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1fd60 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1fd70 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1fd80 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1fd90 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1fda0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1fdb0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1fdc0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1fdd0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1fde0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1fdf0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1fe00 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1fe10 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1fe20 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1fe30 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1fe40 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1fe50 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1fe60 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1fe70 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1fe80 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1fe90 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1fea0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1feb0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1fec0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1fed0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1fee0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1fef0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1ff00 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1ff10 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1ff20 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1ff30 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1ff40 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1ff50 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1ff60 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1ff70 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1ff80 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1ff90 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1ffa0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1ffb0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1ffc0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1ffd0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1ffe0 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1fff0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
20000 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
20010 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
20020 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
20030 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
20040 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
20050 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
20060 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
20070 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
20080 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
20090 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
200a0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
200b0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53  rintf()..**.** S
200c0 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74  ee also:  [built
200d0 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b  -in printf()], [
200e0 70 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e  printf() SQL fun
200f0 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a  ction].*/.char *
20100 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
20110 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
20120 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
20130 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
20140 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
20150 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
20160 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
20170 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
20180 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
20190 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
201a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
201b0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
201c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
201d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
201e0 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
201f0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
20200 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
20210 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
20220 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
20230 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
20240 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
20250 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
20260 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
20270 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
20280 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
20290 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
202a0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
202b0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
202c0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
202d0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
202e0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
202f0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
20300 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20310 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
20320 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
20330 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
20340 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
20350 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
20360 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
20370 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
20380 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
20390 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
203a0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
203b0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
203c0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
203d0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
203e0 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
203f0 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
20400 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
20410 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
20420 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
20430 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
20440 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
20450 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
20460 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
20470 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73  N) routine works
20480 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71   just like.** sq
20490 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
204a0 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
204b0 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d   an unsigned 64-
204c0 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74  bit integer inst
204d0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e  ead.** of a sign
204e0 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  ed 32-bit intege
204f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
20500 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
20510 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
20520 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
20530 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
20540 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
20550 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
20560 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
20570 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
20580 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
20590 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
205a0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
205b0 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
205c0 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
205d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
205e0 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
205f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
20600 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
20610 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
20620 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
20630 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
20640 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
20650 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
20660 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
20670 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
20680 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
20690 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
206a0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
206b0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
206c0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
206d0 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
206e0 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
206f0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
20700 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
20710 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
20720 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
20730 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
20740 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
20750 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
20760 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
20770 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
20780 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
20790 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
207a0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74  realloc(X,N) int
207b0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
207c0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
207d0 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
207e0 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61  cation X to be a
207f0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e  t least N bytes.
20800 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61  .** ^If the X pa
20810 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
20820 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a  e3_realloc(X,N).
20830 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
20840 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
20850 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
20860 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
20870 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
20880 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  (N)..** ^If the 
20890 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  N parameter to s
208a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
208b0 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  ,N) is zero or.*
208c0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
208d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
208e0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
208f0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
20900 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a  qlite3_free(X)..
20910 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
20920 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
20930 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
20940 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
20950 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
20960 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
20970 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75   or NULL if insu
20980 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
20990 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
209a0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
209b0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
209c0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
209d0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
209e0 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
209f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
20a00 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
20a10 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
20a20 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
20a30 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
20a40 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70  c(X,N) and the p
20a50 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
20a60 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
20a70 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20a80 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55  (X,N) returns NU
20a90 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69  LL and N is posi
20aa0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  tive, then the.*
20ab0 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  * prior allocati
20ac0 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  on is not freed.
20ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
20ae0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c  te3_realloc64(X,
20af0 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  N) interfaces wo
20b00 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a  rks the same as.
20b10 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
20b20 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74  oc(X,N) except t
20b30 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69  hat N is a 64-bi
20b40 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
20b50 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
20b60 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64   a 32-bit signed
20b70 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
20b80 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72  ^If X is a memor
20b90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65  y allocation pre
20ba0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
20bb0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
20bc0 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
20bd0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73  e3_malloc64(), s
20be0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
20bf0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  , or sqlite3_rea
20c00 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a  lloc64(), then.*
20c10 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
20c20 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  X) returns the s
20c30 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f  ize of that memo
20c40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e  ry allocation in
20c50 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20   bytes..** ^The 
20c60 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
20c70 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  y sqlite3_msize(
20c80 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  X) might be larg
20c90 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62  er than the numb
20ca0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72  er.** of bytes r
20cb0 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20  equested when X 
20cc0 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20  was allocated.  
20cd0 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20  ^If X is a NULL 
20ce0 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
20cf0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
20d00 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20   returns zero.  
20d10 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73  If X points to s
20d20 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73  omething that is
20d30 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69   not.** the begi
20d40 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20  nning of memory 
20d50 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69  allocation, or i
20d60 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  f it points to a
20d70 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c   formerly.** val
20d80 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  id memory alloca
20d90 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f  tion that has no
20da0 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68  w been freed, th
20db0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
20dc0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73  ** of sqlite3_ms
20dd0 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69  ize(X) is undefi
20de0 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ned and possibly
20df0 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
20e00 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
20e10 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
20e20 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65  malloc(), sqlite
20e30 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  3_realloc(),.** 
20e40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
20e50 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
20e60 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69  realloc64().** i
20e70 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
20e80 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
20e90 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
20ea0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
20eb0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
20ec0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
20ed0 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
20ee0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
20ef0 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
20f00 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
20f10 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
20f20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
20f30 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
20f40 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
20f50 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
20f60 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
20f70 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
20f80 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
20f90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
20fa0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
20fb0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
20fc0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
20fd0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
20fe0 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
20ff0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
21000 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
21010 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
21020 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
21030 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
21040 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
21050 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
21060 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
21070 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
21080 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
21090 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
210a0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
210b0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
210c0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
210d0 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
210e0 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
210f0 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
21100 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
21110 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
21120 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
21130 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
21140 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
21150 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
21160 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
21170 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
21180 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
21190 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
211a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
211b0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
211c0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
211d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
211e0 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
211f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
21200 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
21210 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
21220 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
21230 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
21240 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
21250 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
21260 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
21270 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
21280 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
21290 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
212a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
212b0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
212c0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
212d0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
212e0 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
212f0 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
21300 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
21310 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
21320 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
21330 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
21340 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
21350 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
21360 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74  3_malloc64(sqlit
21370 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
21380 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
21390 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
213a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
213b0 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71  lloc64(void*, sq
213c0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
213d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
213e0 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33  (void*);.sqlite3
213f0 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
21400 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  msize(void*);../
21410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
21420 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
21430 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
21440 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
21450 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
21460 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
21470 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
21480 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
21490 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
214a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
214b0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
214c0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
214d0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
214e0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
214f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
21500 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
21510 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
21520 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
21530 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
21540 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
21550 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
21560 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
21570 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
21580 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
21590 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
215a0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
215b0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
215c0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
215d0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
215e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
215f0 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
21600 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
21610 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
21620 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
21630 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
21640 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
21650 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
21660 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
21670 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
21680 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
21690 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
216a0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
216b0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
216c0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
216d0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
216e0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
216f0 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
21700 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
21710 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
21720 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
21730 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
21740 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
21750 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
21760 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
21770 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
21780 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
21790 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
217a0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
217b0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
217c0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
217d0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
217e0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
217f0 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
21800 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
21810 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
21820 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
21830 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
21840 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
21850 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
21860 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
21870 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
21880 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
21890 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
218a0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
218b0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
218c0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
218d0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
218e0 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
218f0 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
21900 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
21910 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
21920 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
21930 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
21940 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
21950 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
21960 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
21970 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
21980 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
21990 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
219a0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
219b0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
219c0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
219d0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
219e0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
219f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
21a00 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
21a10 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
21a20 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
21a30 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
21a40 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
21a50 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
21a60 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
21a70 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
21a80 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
21a90 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54   buffer P..** ^T
21aa0 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63  he P parameter c
21ab0 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
21ac0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
21ad0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
21ae0 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
21af0 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
21b00 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
21b10 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
21b20 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20  s than one or a 
21b30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
21b40 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e   P, then the PRN
21b50 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75  G is.** seeded u
21b60 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
21b70 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
21b80 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
21b90 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64  thod of.** the d
21ba0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
21bb0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
21bc0 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73  ^If the previous
21bd0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
21be0 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f  utine had an N o
21bf0 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20  f 1 or more and 
21c00 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20  a.** non-NULL P 
21c10 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d  then the pseudo-
21c20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
21c30 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
21c40 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
21c50 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
21c60 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
21c70 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
21c80 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
21c90 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
21ca0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
21cb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21cc0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
21cd0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
21ce0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
21cf0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b  OD: sqlite3.** K
21d00 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72  EYWORDS: {author
21d10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a  izer callback}.*
21d20 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
21d30 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
21d40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21d50 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
21d60 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
21d70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
21d80 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
21d90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
21da0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
21db0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
21dc0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
21dd0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
21de0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
21df0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
21e00 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
21e10 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
21e20 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
21e30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21e40 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
21e50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
21e60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21e70 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64  16_v2()],.** and
21e80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21e90 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20  e16_v3()].  ^At 
21ea0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
21eb0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
21ec0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
21ed0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
21ee0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
21ef0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
21f00 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
21f10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21f20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
21f30 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
21f40 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
21f50 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
21f60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21f70 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
21f80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
21f90 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
21fa0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
21fb0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
21fc0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
21fd0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
21fe0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21ff0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
22000 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
22010 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
22020 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
22030 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
22040 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
22050 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
22060 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
22070 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22080 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
22090 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
220a0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
220b0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
220c0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
220d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
220e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
220f0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
22100 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
22110 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
22120 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
22130 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
22140 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
22150 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
22160 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
22170 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
22180 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
22190 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
221a0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
221b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
221c0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
221d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
221e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
221f0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
22200 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
22210 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
22220 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
22230 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
22240 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
22250 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
22260 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
22270 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
22280 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
22290 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
222a0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
222b0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
222c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
222d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
222e0 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
222f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
22300 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
22310 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
22320 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
22330 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
22340 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
22350 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
22360 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
22370 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
22380 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
22390 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
223a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
223b0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f  e either NULL po
223c0 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74  inters or zero-t
223d0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
223e0 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69  s.** that contai
223f0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74  n additional det
22400 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
22410 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
22420 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69  orized..** Appli
22430 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77  cations must alw
22440 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20  ays be prepared 
22450 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e  to encounter a N
22460 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61  ULL pointer in a
22470 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69  ny.** of the thi
22480 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73  rd through the s
22490 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  ixth parameters 
224a0 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  of the authoriza
224b0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
224c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
224d0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
224e0 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
224f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
22500 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
22510 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
22520 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
22530 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
22540 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
22550 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
22560 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
22570 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
22580 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
22590 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
225a0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
225b0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
225c0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
225d0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
225e0 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
225f0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
22600 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
22610 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
22620 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
22630 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57  f a table..** ^W
22640 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72  hen a table is r
22650 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b  eferenced by a [
22660 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63  SELECT] but no c
22670 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65  olumn values are
22680 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72  .** extracted fr
22690 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66  om that table (f
226a0 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20  or example in a 
226b0 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53  query like.** "S
226c0 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46  ELECT count(*) F
226d0 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74  ROM tab") then t
226e0 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  he [SQLITE_READ]
226f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22700 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  back.** is invok
22710 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74  ed once for that
22720 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f   table with a co
22730 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69  lumn name that i
22740 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
22750 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  g..** ^If the ac
22760 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
22770 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
22780 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
22790 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
227a0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
227b0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
227c0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
227d0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
227e0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
227f0 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
22800 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
22810 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
22820 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
22830 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
22840 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
22850 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
22860 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
22870 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
22880 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
22890 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
228a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
228b0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
228c0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
228d0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
228e0 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
228f0 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
22900 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
22910 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
22920 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
22930 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
22940 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
22950 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
22960 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
22970 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
22980 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
22990 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
229a0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
229b0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
229c0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
229d0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
229e0 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
229f0 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
22a00 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
22a10 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
22a20 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
22a30 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
22a40 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
22a50 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
22a60 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
22a70 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
22a80 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
22a90 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
22aa0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
22ab0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
22ac0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
22ad0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
22ae0 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
22af0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
22b00 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
22b10 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
22b20 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
22b30 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
22b40 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
22b50 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
22b60 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
22b70 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
22b80 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
22b90 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
22ba0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
22bb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
22bc0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
22bd0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
22be0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
22bf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
22c00 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
22c10 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
22c20 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22c30 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
22c40 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
22c50 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
22c60 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
22c70 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
22c80 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
22c90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
22ca0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
22cb0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
22cc0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22cd0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
22ce0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
22cf0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
22d00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22d10 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
22d20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22d30 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
22d40 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
22d50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
22d60 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
22d70 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
22d80 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
22d90 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
22da0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
22db0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
22dc0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
22dd0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
22de0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
22df0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
22e00 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
22e10 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
22e20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
22e30 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
22e40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
22e50 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
22e60 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
22e70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
22e80 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
22e90 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
22ea0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
22eb0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
22ec0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
22ed0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
22ee0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
22ef0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
22f00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
22f10 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
22f20 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
22f30 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
22f40 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
22f50 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
22f60 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
22f70 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
22f80 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
22f90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
22fa0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
22fb0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
22fc0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
22fd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
22fe0 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
22ff0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
23000 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
23010 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
23020 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
23030 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
23040 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
23050 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
23060 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
23070 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
23080 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
23090 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
230a0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
230b0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
230c0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
230d0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
230e0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
230f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23100 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
23110 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
23120 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
23130 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
23140 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
23150 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
23160 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
23170 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
23180 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
23190 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
231a0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
231b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
231c0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
231d0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
231e0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
231f0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
23200 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
23210 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
23220 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
23230 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69  sed as a [confli
23240 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f  ct resolution mo
23250 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  de].** returned 
23260 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
23270 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
23280 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
23290 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
232a0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
232b0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
232c0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
232d0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
232e0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
232f0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
23300 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
23310 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
23320 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
23330 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
23340 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
23350 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
23360 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23370 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
23380 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
23390 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
233a0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
233b0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
233c0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
233d0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
233e0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
233f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
23400 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
23410 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
23420 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
23430 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
23440 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
23450 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
23460 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
23470 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
23480 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
23490 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
234a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
234b0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
234c0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
234d0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
234e0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
234f0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
23500 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
23510 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
23520 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
23530 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
23540 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
23550 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
23560 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
23570 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
23580 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
23590 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
235a0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
235b0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
235c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
235d0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
235e0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
235f0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
23600 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
23610 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
23620 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
23630 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
23640 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
23650 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
23660 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
23670 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
23680 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
23690 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
236a0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
236b0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
236c0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
236d0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
236e0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
236f0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
23700 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23710 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
23720 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
23730 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
23740 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
23750 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
23760 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
23770 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
23780 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
23790 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
237a0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
237b0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
237c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
237d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
237e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
237f0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
23800 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
23810 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
23820 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23830 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
23840 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
23850 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
23860 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23870 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23880 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
23890 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
238a0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
238b0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
238c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
238d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
238e0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
238f0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
23900 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23910 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23920 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
23930 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
23940 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
23950 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
23960 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23970 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
23980 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
23990 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
239a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
239b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
239c0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
239d0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
239e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
239f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23a00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23a10 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
23a20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
23a30 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
23a40 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
23a50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23a60 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
23a70 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
23a80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23a90 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23aa0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23ab0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
23ac0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
23ad0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
23ae0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23af0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23b00 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
23b10 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
23b20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
23b30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23b40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23b50 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
23b60 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
23b70 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
23b80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
23b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23ba0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
23bb0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
23bc0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
23bd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23be0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23bf0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
23c00 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
23c10 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
23c20 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
23c30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
23c40 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
23c50 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
23c60 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
23c70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23c80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
23c90 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
23ca0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
23cb0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23cc0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23cd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
23ce0 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
23cf0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
23d00 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
23d10 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
23d20 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
23d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23d40 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
23d50 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
23d60 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
23d70 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
23d80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
23d90 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
23da0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
23db0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23dc0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
23dd0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
23de0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
23df0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23e00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23e10 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
23e20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
23e30 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
23e40 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
23e50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23e60 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
23e70 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
23e80 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
23e90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
23ea0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23eb0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
23ec0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
23ed0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
23ee0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23ef0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23f00 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
23f10 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
23f20 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
23f30 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
23f40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23f50 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
23f60 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
23f70 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
23f80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23f90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23fa0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
23fb0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
23fc0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23fd0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23fe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23ff0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
24000 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
24010 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
24020 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
24030 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24040 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
24050 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
24060 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
24070 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
24080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24090 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
240a0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
240b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
240c0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
240d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
240e0 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
240f0 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
24100 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
24110 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
24120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
24130 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
24140 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
24150 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
24160 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
24170 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
24180 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
24190 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
241a0 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
241b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
241c0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
241d0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ng Functions.** 
241e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
241f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24200 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61  ines are depreca
24210 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71  ted. Use the [sq
24220 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
24230 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
24240 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f  nstead of the ro
24250 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64  utines described
24260 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
24270 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
24280 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
24290 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
242a0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
242b0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
242c0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
242d0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
242e0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
242f0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
24300 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
24310 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
24320 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
24330 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
24340 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
24350 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
24360 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
24370 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
24380 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24390 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
243a0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
243b0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
243c0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
243d0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
243e0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
243f0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
24400 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
24410 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
24420 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
24430 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
24440 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
24450 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
24460 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
24470 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
24480 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
24490 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
244a0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
244b0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
244c0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
244d0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
244e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
244f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
24500 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
24510 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
24520 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
24530 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
24540 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
24550 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
24560 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
24570 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
24580 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
24590 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
245a0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
245b0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
245c0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
245d0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
245e0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
245f0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
24600 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
24610 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
24620 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
24630 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
24640 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
24650 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
24660 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
24670 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
24680 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
24690 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
246a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
246b0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
246c0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
246d0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
246e0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
246f0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
24700 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
24710 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
24720 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
24730 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
24740 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
24750 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
24760 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
24770 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
24780 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
24790 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
247a0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
247b0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
247c0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
247d0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
247e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
247f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52  ..*/.SQLITE_DEPR
24800 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c  ECATED void *sql
24810 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
24820 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54  e3*,.   void(*xT
24830 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
24840 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
24850 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
24860 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TED void *sqlite
24870 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
24880 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
24890 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
248a0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
248b0 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
248c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
248d0 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65  F: SQL Trace Eve
248e0 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  nt Codes.** KEYW
248f0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41  ORDS: SQLITE_TRA
24900 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  CE.**.** These c
24910 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66  onstants identif
24920 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65  y classes of eve
24930 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  nts that can be 
24940 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69  monitored.** usi
24950 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
24960 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63  trace_v2()] trac
24970 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20  ing logic.  The 
24980 4d 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  M argument.** to
24990 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
249a0 76 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20  v2(D,M,X,P)] is 
249b0 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61  an OR-ed combina
249c0 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  tion of one or m
249d0 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  ore of.** the fo
249e0 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
249f0 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61  s.  ^The first a
24a00 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
24a10 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
24a20 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   is one of the f
24a30 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e  ollowing constan
24a40 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72  ts..**.** New tr
24a50 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  acing constants 
24a60 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
24a70 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
24a80 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
24a90 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75  callback has fou
24aa0 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61  r arguments: xCa
24ab0 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
24ac0 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
24ad0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
24ae0 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63  e integer type c
24af0 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e  odes above..** ^
24b00 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
24b10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
24b20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
24b30 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
24b40 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d  .** fourth argum
24b50 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
24b60 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  trace_v2()]..** 
24b70 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
24b80 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
24b90 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
24ba0 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
24bb0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
24bc0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
24bd0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
24be0 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a  ACE_STMT</dt>.**
24bf0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
24c00 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62  TRACE_STMT callb
24c10 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
24c20 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73  hen a prepared s
24c30 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73  tatement.** firs
24c40 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67  t begins running
24c50 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74   and possibly at
24c60 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72   other times dur
24c70 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75  ing the.** execu
24c80 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70  tion of the prep
24c90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20  ared statement, 
24ca0 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73  such as at the s
24cb0 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  tart of each.** 
24cc0 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
24cd0 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d  am. ^The P argum
24ce0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
24cf0 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   to the.** [prep
24d00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
24d10 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74   ^The X argument
24d20 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
24d30 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a   a string which.
24d40 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61  ** is the unexpa
24d50 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66  nded SQL text of
24d60 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
24d70 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51  atement or an SQ
24d80 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68  L comment .** th
24d90 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65  at indicates the
24da0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61   invocation of a
24db0 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20   trigger.  ^The 
24dc0 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d  callback can com
24dd0 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65  pute.** the same
24de0 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64   text that would
24df0 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72   have been retur
24e00 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63  ned by the legac
24e10 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  y [sqlite3_trace
24e20 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
24e30 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20   by using the X 
24e40 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20  argument when X 
24e50 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22  begins with "--"
24e60 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a   and invoking.**
24e70 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   [sqlite3_expand
24e80 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72  ed_sql(P)] other
24e90 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  wise..**.** [[SQ
24ea0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
24eb0 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  LE]] <dt>SQLITE_
24ec0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64  TRACE_PROFILE</d
24ed0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
24ee0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
24ef0 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76  LE callback prov
24f00 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65  ides approximate
24f10 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69  ly the same.** i
24f20 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73  nformation as is
24f30 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
24f40 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
24f50 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  e()] callback..*
24f60 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
24f70 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
24f80 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
24f90 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
24fa0 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
24fb0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d   points to a 64-
24fc0 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63  bit integer whic
24fd0 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74  h is the estimat
24fe0 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d  ed of.** the num
24ff0 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  ber of nanosecon
25000 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61  d that the prepa
25010 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  red statement to
25020 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54  ok to run..** ^T
25030 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  he SQLITE_TRACE_
25040 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b  PROFILE callback
25050 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
25060 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
25070 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  inishes..**.** [
25080 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  [SQLITE_TRACE_RO
25090 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  W]] <dt>SQLITE_T
250a0 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a  RACE_ROW</dt>.**
250b0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
250c0 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61  TRACE_ROW callba
250d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
250e0 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65  enever a prepare
250f0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67  d.** statement g
25100 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c  enerates a singl
25110 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e  e row of result.
25120 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67    .** ^The P arg
25130 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
25140 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
25150 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
25160 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
25170 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
25180 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
25190 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74  RACE_CLOSE]] <dt
251a0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  >SQLITE_TRACE_CL
251b0 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  OSE</dt>.** <dd>
251c0 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
251d0 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20  _CLOSE callback 
251e0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
251f0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  a database.** co
25200 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
25210 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
25220 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
25230 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
25240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
25250 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ject.** and the 
25260 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e  X argument is un
25270 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  used..** </dl>.*
25280 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25290 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20  _TRACE_STMT     
252a0 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53    0x01.#define S
252b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
252c0 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66  ILE    0x02.#def
252d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
252e0 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34  _ROW        0x04
252f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25300 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20  TRACE_CLOSE     
25310 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   0x08../*.** CAP
25320 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
25330 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Hook.** METHOD:
25340 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
25350 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
25360 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e  e_v2(D,M,X,P) in
25370 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
25380 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61  s a trace callba
25390 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
253a0 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61   against [databa
253b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
253c0 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79  , using property
253d0 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63   mask M.** and c
253e0 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50  ontext pointer P
253f0 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c  .  ^If the X cal
25400 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c  lback is.** NULL
25410 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73   or if the M mas
25420 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  k is zero, then 
25430 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62  tracing is disab
25440 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61  led.  The.** M a
25450 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
25460 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52  e the bitwise OR
25470 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
25480 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f  of.** zero or mo
25490 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  re [SQLITE_TRACE
254a0 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  ] constants..**.
254b0 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f  ** ^Each call to
254c0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
254d0 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
254e0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76  e3_trace_v2() ov
254f0 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e  errides .** (can
25500 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20  cels) any prior 
25510 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
25520 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69  _trace() or sqli
25530 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a  te3_trace_v2()..
25540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c  **.** ^The X cal
25550 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
25560 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66   whenever any of
25570 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e   the events iden
25580 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61  tified by .** ma
25590 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68  sk M occur.  ^Th
255a0 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e  e integer return
255b0 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20   value from the 
255c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72  callback is curr
255d0 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64  ently.** ignored
255e0 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61  , though this ma
255f0 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  y change in futu
25600 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61  re releases.  Ca
25610 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d  llback.** implem
25620 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
25630 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20   return zero to 
25640 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f  ensure future co
25650 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
25660 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
25670 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
25680 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65  with four argume
25690 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c  nts: callback(T,
256a0 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
256b0 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
256c0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
256d0 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74  _TRACE].** const
256e0 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65  ants to indicate
256f0 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63   why the callbac
25700 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  k was invoked..*
25710 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e  * ^The C argumen
25720 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  t is a copy of t
25730 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  he context point
25740 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  er..** The P and
25750 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
25760 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
25770 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
25780 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  on T..**.** The 
25790 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
257a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
257b0 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c  intended to repl
257c0 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  ace the legacy.*
257d0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
257e0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61  lite3_trace()] a
257f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  nd [sqlite3_prof
25800 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20  ile()], both of 
25810 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70  which.** are dep
25820 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20  recated..*/.int 
25830 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
25840 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
25850 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a  unsigned uMask,.
25860 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b    int(*xCallback
25870 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a  )(unsigned,void*
25880 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20  ,void*,void*),. 
25890 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a   void *pCtx.);..
258a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
258b0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
258c0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
258d0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
258e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
258f0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
25900 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
25910 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
25920 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
25930 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
25940 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
25950 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
25960 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
25970 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
25980 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
25990 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
259a0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
259b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
259c0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
259d0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
259e0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
259f0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
25a00 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
25a10 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
25a20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
25a30 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
25a40 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
25a50 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
25a60 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
25a70 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
25a80 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
25a90 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
25aa0 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
25ab0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
25ac0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
25ad0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
25ae0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
25af0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
25b00 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
25b10 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
25b20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
25b30 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
25b40 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
25b50 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
25b60 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
25b70 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
25b80 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
25b90 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
25ba0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
25bb0 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
25bc0 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
25bd0 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
25be0 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
25bf0 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
25c00 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
25c10 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
25c20 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
25c30 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
25c40 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
25c50 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
25c60 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
25c70 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
25c80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
25c90 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
25ca0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
25cb0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
25cc0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
25cd0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
25ce0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
25cf0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
25d00 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
25d10 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
25d20 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
25d30 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
25d40 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
25d50 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
25d60 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
25d70 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
25d80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25d90 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
25da0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
25db0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
25dc0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
25dd0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
25de0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
25df0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
25e00 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
25e10 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
25e20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
25e30 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
25e40 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
25e50 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
25e60 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
25e70 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
25e80 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
25e90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25ea0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
25eb0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
25ec0 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
25ed0 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
25ee0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
25ef0 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
25f00 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
25f10 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
25f20 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
25f30 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
25f40 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
25f50 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
25f60 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
25f70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
25f80 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
25f90 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
25fa0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
25fb0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
25fc0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
25fd0 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
25fe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
25ff0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
26000 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
26010 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
26020 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
26030 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
26040 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
26050 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
26060 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
26070 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
26080 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
26090 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
260a0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
260b0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
260c0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
260d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
260e0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
260f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
26100 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
26110 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
26120 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
26130 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
26140 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
26150 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
26160 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
26170 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
26180 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
26190 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
261a0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
261b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
261c0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
261d0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
261e0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
261f0 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
26200 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
26210 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
26220 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
26230 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
26240 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
26250 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
26260 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
26270 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
26280 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
26290 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
262a0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
262b0 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
262c0 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
262d0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
262e0 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
262f0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
26300 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
26310 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
26320 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
26330 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
26340 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
26350 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
26360 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
26370 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
26380 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
26390 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
263a0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
263b0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
263c0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
263d0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
263e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
263f0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
26400 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
26410 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
26420 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
26430 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
26440 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
26450 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
26460 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
26470 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
26480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
26490 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
264a0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
264b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
264c0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
264d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
264e0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
264f0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
26500 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
26510 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
26520 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
26530 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
26540 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
26550 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
26560 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
26570 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
26580 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
26590 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
265a0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
265b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
265c0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
265d0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
265e0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
265f0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
26600 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
26610 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
26620 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
26630 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
26640 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
26650 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
26660 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
26670 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
26680 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
26690 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
266a0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
266b0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
266c0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
266d0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
266e0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
266f0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
26700 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
26710 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
26720 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
26730 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
26740 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
26750 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
26760 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
26770 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
26780 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
26790 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
267a0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
267b0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
267c0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
267d0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
267e0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
267f0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
26800 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
26810 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
26820 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
26830 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
26840 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
26850 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
26860 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
26870 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
26880 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26890 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
268a0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
268b0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
268c0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
268d0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
268e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
268f0 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
26900 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
26910 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
26920 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
26930 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
26940 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
26950 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
26960 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
26970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
26980 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
26990 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
269a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
269b0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
269c0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
269d0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
269e0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
269f0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
26a00 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
26a10 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
26a20 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
26a30 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
26a40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
26a50 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
26a60 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
26a70 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
26a80 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
26a90 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
26aa0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
26ab0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
26ac0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
26ad0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
26ae0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
26af0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
26b00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
26b10 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
26b20 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
26b30 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
26b40 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
26b50 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
26b60 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
26b70 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
26b80 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
26b90 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
26ba0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
26bb0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
26bc0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
26bd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26be0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
26bf0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
26c00 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
26c10 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
26c20 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
26c30 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
26c40 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
26c50 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
26c60 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
26c70 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
26c80 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
26c90 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
26ca0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
26cb0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
26cc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26cd0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
26ce0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
26cf0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
26d00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
26d10 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
26d20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
26d30 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
26d40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
26d50 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
26d60 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
26d70 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
26d80 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
26d90 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
26da0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
26db0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
26dc0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
26dd0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
26de0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
26df0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
26e00 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
26e10 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
26e20 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
26e30 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
26e40 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
26e50 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
26e60 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
26e70 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
26e80 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
26e90 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
26ea0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
26eb0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
26ec0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
26ed0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
26ee0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
26ef0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
26f00 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
26f10 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
26f20 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
26f30 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
26f40 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
26f50 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
26f60 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
26f70 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
26f80 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
26f90 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
26fa0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
26fb0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
26fc0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
26fd0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
26fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
26ff0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
27000 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
27010 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
27020 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
27030 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
27040 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
27050 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
27060 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
27070 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
27080 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
27090 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
270a0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
270b0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
270c0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
270d0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
270e0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
270f0 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
27100 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
27110 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
27120 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
27130 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
27140 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
27150 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
27160 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
27170 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
27180 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
27190 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
271a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
271b0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
271c0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
271d0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
271e0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20   option..** URI 
271f0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
27200 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
27210 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
27220 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
27230 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
27240 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
27250 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
27260 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
27270 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
27280 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
27290 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
272a0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
272b0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
272c0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
272d0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
272e0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
272f0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
27300 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
27310 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
27320 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
27330 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
27340 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
27350 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
27360 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
27370 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
27380 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
27390 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
273a0 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
273b0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
273c0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
273d0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
273e0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
273f0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
27400 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
27410 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
27420 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
27430 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
27440 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
27450 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
27460 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
27470 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
27480 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
27490 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
274a0 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
274b0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
274c0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
274d0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
274e0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
274f0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
27500 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
27510 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
27520 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
27530 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
27540 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
27550 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77  path. .** ^(On w
27560 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
27570 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
27580 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
27590 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
275a0 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
275b0 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a  g. "C:").)^.**.*
275c0 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
275d0 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
275e0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
275f0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
27600 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
27610 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
27620 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
27630 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
27640 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
27650 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
27660 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
27670 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  ]..** SQLite and
27680 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56   its built-in [V
27690 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20  FSes] interpret 
276a0 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
276b0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
276c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
276d0 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
276e0 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
276f0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
27700 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
27710 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
27720 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
27730 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
27740 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
27750 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
27760 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
27770 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
27780 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
27790 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
277a0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
277b0 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
277c0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
277d0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
277e0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
277f0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
27800 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
27810 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
27820 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27830 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
27840 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
27850 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
27860 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
27870 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
27880 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
27890 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
278a0 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
278b0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
278c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
278d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
278e0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
278f0 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
27900 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
27910 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
27920 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
27930 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20  ,.**     "rwc", 
27940 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74  or "memory". Att
27950 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
27960 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
27970 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61  alue is.**     a
27980 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
27990 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
279a0 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
279b0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
279c0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
279d0 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
279e0 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
279f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
27a00 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
27a10 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
27a20 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
27a30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
27a40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
27a50 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
27a60 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
27a70 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
27a80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
27a90 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
27aa0 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
27ab0 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
27ac0 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
27ad0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
27ae0 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
27af0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
27b00 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
27b10 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
27b20 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
27b30 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
27b40 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
27b50 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
27b60 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
27b70 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65  CREATE.  ^If the
27b80 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a   mode option is.
27b90 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d  **     set to "m
27ba0 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75  emory" then a pu
27bb0 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  re [in-memory da
27bc0 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76  tabase] that nev
27bd0 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20  er reads.**     
27be0 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64  or writes from d
27bf0 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74  isk is used. ^It
27c00 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
27c10 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
27c20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d  for.**     the m
27c30 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
27c40 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72  at is less restr
27c50 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
27c60 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
27c70 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70       the flags p
27c80 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69  assed in the thi
27c90 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
27ca0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27cb0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
27cc0 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
27cd0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
27ce0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
27cf0 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
27d00 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
27d10 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
27d20 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
27d30 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
27d40 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
27d50 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
27d60 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
27d70 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
27d80 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
27d90 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
27da0 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
27db0 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
27dc0 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
27dd0 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
27de0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
27df0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
27e00 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
27e10 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
27e20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27e30 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
27e40 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
27e50 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
27e60 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
27e70 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
27e80 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
27e90 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73   behavior reques
27ea0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
27eb0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
27ec0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
27ed0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
27ee0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
27ef0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70  **.**  <li> <b>p
27f00 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73  sow</b>: ^The ps
27f10 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64  ow parameter ind
27f20 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f  icates whether o
27f30 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20  r not the.**    
27f40 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
27f50 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
27f60 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
27f70 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
27f80 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
27f90 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
27fa0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
27fb0 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  sides..**.**  <l
27fc0 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e  i> <b>nolock</b>
27fd0 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61  : ^The nolock pa
27fe0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
27ff0 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d  lean query param
28000 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63  eter.**     whic
28010 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65  h if set disable
28020 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69  s file locking i
28030 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  n rollback journ
28040 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a  al modes.  This.
28050 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c  **     is useful
28060 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61   for accessing a
28070 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66   database on a f
28080 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64  ilesystem that d
28090 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73  oes not.**     s
280a0 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20  upport locking. 
280b0 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62   Caution:  Datab
280c0 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d  ase corruption m
280d0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74  ight result if t
280e0 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72  wo.**     or mor
280f0 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74  e processes writ
28100 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  e to the same da
28110 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f  tabase and any o
28120 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20  ne of those.**  
28130 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65     processes use
28140 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a  s nolock=1..**.*
28150 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74  *  <li> <b>immut
28160 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69  able</b>: ^The i
28170 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74  mmutable paramet
28180 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
28190 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
281a0 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69  ameter that indi
281b0 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64  cates that the d
281c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
281d0 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  stored on.**    
281e0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
281f0 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62  .  ^When immutab
28200 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74  le is set, SQLit
28210 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
28220 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61  he.**     databa
28230 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62  se file cannot b
28240 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  e changed, even 
28250 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74  by a process wit
28260 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20  h higher.**     
28270 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73  privilege, and s
28280 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  o the database i
28290 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e  s opened read-on
282a0 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69  ly and all locki
282b0 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68  ng.**     and ch
282c0 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69  ange detection i
282d0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75  s disabled.  Cau
282e0 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68  tion: Setting th
282f0 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20  e immutable.**  
28300 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61     property on a
28310 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
28320 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74  hat does in fact
28330 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75   change can resu
28340 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63  lt.**     in inc
28350 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73  orrect query res
28360 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ults and/or [SQL
28370 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72  ITE_CORRUPT] err
28380 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20  ors..**     See 
28390 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
283a0 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a  CAP_IMMUTABLE]..
283b0 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75  **       .** </u
283c0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
283d0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
283e0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
283f0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
28400 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
28410 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
28420 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
28430 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
28440 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
28450 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
28460 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
28470 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
28480 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
28490 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
284a0 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
284b0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
284c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
284d0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
284e0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
284f0 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
28500 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
28510 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
28520 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
28530 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
28540 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
28550 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
28560 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
28570 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
28580 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
28590 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
285a0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
285b0 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
285c0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
285d0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
285e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
285f0 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
28600 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
28610 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
28620 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
28630 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
28640 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
28650 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
28660 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
28670 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
28680 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
28690 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
286a0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
286b0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
286c0 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
286d0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
286e0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
286f0 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
28700 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
28710 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
28720 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
28730 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
28740 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
28750 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
28760 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
28770 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
28780 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
28790 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
287a0 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
287b0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
287c0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
287d0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
287e0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
287f0 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
28800 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
28810 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
28820 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
28830 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
28840 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
28850 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
28860 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
28870 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
28880 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
28890 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
288a0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
288b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
288c0 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
288d0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
288e0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
288f0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
28900 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
28910 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
28920 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
28930 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
28940 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
28950 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
28960 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
28970 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74  .db?vfs=unix-dot
28980 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  file <td>.**    
28990 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
289a0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
289b0 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
289c0 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
289d0 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20  dotfile".**     
289e0 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64       that uses d
289f0 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63  ot-files in plac
28a00 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73  e of posix advis
28a10 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20  ory locking..** 
28a20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
28a30 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
28a40 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
28a50 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
28a60 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
28a70 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
28a80 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
28a90 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
28aa0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
28ab0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
28ac0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
28ad0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
28ae0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
28af0 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
28b00 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
28b10 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
28b20 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
28b30 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
28b40 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
28b50 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
28b60 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
28b70 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
28b80 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
28b90 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
28ba0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
28bb0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
28bc0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
28bd0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
28be0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
28bf0 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
28c00 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
28c10 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
28c20 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
28c30 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
28c40 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
28c50 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
28c60 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
28c70 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
28c80 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
28c90 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
28ca0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
28cb0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
28cc0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
28cd0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
28ce0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
28cf0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
28d00 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
28d10 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
28d20 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
28d30 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
28d40 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
28d50 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
28d60 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
28d70 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
28d80 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
28d90 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
28da0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
28db0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
28dc0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
28dd0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
28de0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
28df0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
28e00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
28e10 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
28e20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
28e30 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
28e40 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
28e50 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
28e60 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
28e70 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
28e80 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
28e90 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
28ea0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
28eb0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
28ec0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
28ed0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
28ee0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
28ef0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
28f00 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
28f10 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71  ctory].*/.int sq
28f20 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
28f30 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
28f40 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
28f50 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
28f60 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
28f70 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
28f80 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
28f90 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
28fa0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
28fb0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
28fc0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
28fd0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
28fe0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
28ff0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
29000 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
29010 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
29020 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
29030 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
29040 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
29050 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
29060 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
29070 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
29080 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
29090 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
290a0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
290b0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
290c0 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
290d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
290e0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
290f0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
29100 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
29110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29120 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
29130 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
29140 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
29150 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
29160 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
29170 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
29180 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
29190 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
291a0 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
291b0 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
291c0 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
291d0 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
291e0 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
291f0 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
29200 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
29210 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
29220 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
29230 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
29240 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
29250 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
29260 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
29270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
29280 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
29290 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
292a0 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
292b0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
292c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
292d0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
292e0 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
292f0 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
29300 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
29310 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
29320 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
29330 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
29340 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
29350 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
29360 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
29370 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
29380 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
29390 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
293a0 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
293b0 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
293c0 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
293d0 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
293e0 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
293f0 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
29400 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
29410 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
29420 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
29430 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
29440 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
29450 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
29460 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
29470 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
29480 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
29490 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
294a0 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
294b0 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
294c0 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
294d0 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
294e0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
294f0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
29500 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
29510 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
29520 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
29530 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
29540 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
29550 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
29560 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
29570 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
29580 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
29590 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
295a0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
295b0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
295c0 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
295d0 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
295e0 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
295f0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
29600 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
29610 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
29620 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
29630 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
29640 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
29650 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
29660 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
29670 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
29680 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
29690 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
296a0 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
296b0 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
296c0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
296d0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
296e0 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
296f0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
29700 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
29710 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
29720 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
29730 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
29740 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
29750 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
29760 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
29770 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
29780 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
29790 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
297a0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
297b0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
297c0 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
297d0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
297e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
297f0 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
29800 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
29810 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
29820 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
29830 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
29840 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
29850 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
29860 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
29870 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
29880 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
29890 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
298a0 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
298b0 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
298c0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
298d0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
298e0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
298f0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
29900 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
29910 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ble..*/.const ch
29920 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
29930 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
29940 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
29950 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
29960 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ram);.int sqlite
29970 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
29980 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
29990 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
299a0 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
299b0 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  t);.sqlite3_int6
299c0 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
299d0 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
299e0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
299f0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
29a00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29a10 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
29a20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48  Messages.** METH
29a30 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
29a40 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
29a50 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20  ecent sqlite3_* 
29a60 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  API call associa
29a70 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61  ted with .** [da
29a80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29a90 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65  n] D failed, the
29aa0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72  n the sqlite3_er
29ab0 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61  rcode(D) interfa
29ac0 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  ce.** returns th
29ad0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
29ae0 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  t code] or [exte
29af0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
29b00 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50  ] for that.** AP
29b10 49 20 63 61 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20  I call..** ^The 
29b20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
29b30 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
29b40 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
29b50 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
29b60 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
29b70 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
29b80 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
29b90 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
29ba0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
29bb0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
29bc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
29bd0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  es returned by s
29be0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
29bf0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
29c00 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
29c10 6f 64 65 28 29 20 6d 69 67 68 74 20 63 68 61 6e  ode() might chan
29c20 67 65 20 77 69 74 68 20 65 61 63 68 20 41 50 49  ge with each API
29c30 20 63 61 6c 6c 2e 0a 2a 2a 20 45 78 63 65 70 74   call..** Except
29c40 2c 20 74 68 65 72 65 20 61 72 65 20 73 6f 6d 65  , there are some
29c50 20 69 6e 74 65 72 66 61 63 65 73 20 74 68 61 74   interfaces that
29c60 20 61 72 65 20 67 75 61 72 61 6e 74 65 65 64 20   are guaranteed 
29c70 74 6f 20 6e 65 76 65 72 0a 2a 2a 20 63 68 61 6e  to never.** chan
29c80 67 65 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ge the value of 
29c90 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 2e 20  the error code. 
29ca0 20 54 68 65 20 65 72 72 6f 72 2d 63 6f 64 65 20   The error-code 
29cb0 70 72 65 73 65 72 76 69 6e 67 0a 2a 2a 20 69 6e  preserving.** in
29cc0 74 65 72 66 61 63 65 73 20 61 72 65 3a 0a 2a 2a  terfaces are:.**
29cd0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
29ce0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
29cf0 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74  ().** <li> sqlit
29d00 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
29d10 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71  ode().** <li> sq
29d20 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 0a 2a  lite3_errmsg().*
29d30 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65  * <li> sqlite3_e
29d40 72 72 6d 73 67 31 36 28 29 0a 2a 2a 20 3c 2f 75  rrmsg16().** </u
29d50 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  l>.**.** ^The sq
29d60 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
29d70 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
29d80 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
29d90 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
29da0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
29db0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
29dc0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
29dd0 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
29de0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
29df0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
29e00 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
29e10 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
29e20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
29e30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
29e40 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
29e50 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
29e60 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
29e70 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
29e80 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
29e90 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
29ea0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
29eb0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
29ec0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
29ed0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
29ee0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
29ef0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29f00 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
29f10 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
29f20 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
29f30 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
29f40 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
29f50 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
29f60 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
29f70 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
29f80 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
29f90 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
29fa0 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
29fb0 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
29fc0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
29fd0 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
29fe0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
29ff0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
2a000 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
2a010 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
2a020 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
2a030 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
2a040 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
2a050 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
2a060 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
2a070 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
2a080 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
2a090 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2a0a0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
2a0b0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
2a0c0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
2a0d0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
2a0e0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
2a0f0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
2a100 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
2a110 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
2a120 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
2a130 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
2a140 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
2a150 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
2a160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2a170 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
2a180 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
2a190 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
2a1a0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
2a1b0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
2a1c0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
2a1d0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
2a1e0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
2a1f0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
2a200 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
2a210 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
2a220 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
2a230 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
2a240 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
2a250 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
2a260 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
2a270 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
2a280 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
2a290 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
2a2a0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
2a2b0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
2a2c0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
2a2d0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
2a2e0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
2a2f0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
2a300 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2a310 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
2a320 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
2a330 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
2a340 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
2a350 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a360 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
2a370 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
2a380 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
2a390 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  16(sqlite3*);.co
2a3a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2a3b0 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
2a3c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a3d0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2a3e0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
2a3f0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
2a400 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
2a410 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2a420 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
2a430 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
2a440 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
2a450 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
2a460 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73  ment that.** has
2a470 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69   been compiled i
2a480 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20  nto binary form 
2a490 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20  and is ready to 
2a4a0 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a  be evaluated..**
2a4b0 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63  .** Think of eac
2a4c0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
2a4d0 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f  as a separate co
2a4e0 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20  mputer program. 
2a4f0 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   The.** original
2a500 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75   SQL text is sou
2a510 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65  rce code.  A pre
2a520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a530 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68  object .** is th
2a540 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63  e compiled objec
2a550 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c  t code.  All SQL
2a560 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2a570 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65  ed into a.** pre
2a580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a590 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65  before it can be
2a5a0 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
2a5b0 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20  life-cycle of a 
2a5c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a5d0 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c  nt object usuall
2a5e0 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73  y goes like this
2a5f0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
2a600 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
2a610 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a620 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  nt object using 
2a630 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a640 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  _v2()]..** <li> 
2a650 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
2a660 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
2a670 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2a680 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
2a690 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
2a6a0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
2a6b0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2a6c0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
2a6d0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
2a6e0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
2a6f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a700 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
2a710 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
2a720 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
2a730 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
2a740 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
2a750 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
2a760 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
2a770 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
2a780 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
2a790 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64  * </ol>.*/.typed
2a7a0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2a7b0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
2a7c0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
2a7d0 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
2a7e0 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  imits.** METHOD:
2a7f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
2a800 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
2a810 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
2a820 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
2a830 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
2a840 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
2a850 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
2a860 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
2a870 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2a880 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
2a890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2a8a0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
2a8b0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
2a8c0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
2a8d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2a8e0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
2a8f0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
2a900 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
2a910 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
2a920 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
2a930 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
2a940 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
2a950 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
2a960 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
2a970 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
2a980 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
2a990 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
2a9a0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
2a9b0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
2a9c0 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
2a9d0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
2a9e0 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
2a9f0 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
2aa00 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
2aa10 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
2aa20 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
2aa30 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
2aa40 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
2aa50 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
2aa60 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
2aa70 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
2aa80 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
2aa90 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
2aaa0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
2aab0 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
2aac0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
2aad0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
2aae0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
2aaf0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
2ab00 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
2ab10 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
2ab20 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
2ab30 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2ab40 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
2ab50 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
2ab60 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
2ab70 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
2ab80 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
2ab90 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
2aba0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
2abb0 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
2abc0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
2abd0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
2abe0 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
2abf0 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
2ac00 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
2ac10 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
2ac20 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
2ac30 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
2ac40 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
2ac50 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
2ac60 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
2ac70 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
2ac80 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
2ac90 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
2aca0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
2acb0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
2acc0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
2acd0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
2ace0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
2acf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
2ad00 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
2ad10 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
2ad20 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
2ad30 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
2ad40 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
2ad50 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
2ad60 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
2ad70 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
2ad80 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
2ad90 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
2ada0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
2adb0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
2adc0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
2add0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
2ade0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
2adf0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
2ae00 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
2ae10 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
2ae20 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
2ae30 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
2ae40 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
2ae50 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
2ae60 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
2ae70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
2ae80 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
2ae90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
2aea0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
2aeb0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
2aec0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
2aed0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
2aee0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
2aef0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
2af00 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
2af10 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
2af20 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
2af30 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
2af40 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
2af50 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
2af60 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
2af70 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
2af80 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2af90 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2afa0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
2afb0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
2afc0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
2afd0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
2afe0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
2aff0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2b000 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
2b010 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
2b020 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
2b030 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
2b040 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
2b050 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
2b060 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
2b070 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
2b080 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
2b090 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
2b0a0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
2b0b0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
2b0c0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
2b0d0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
2b0e0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
2b0f0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
2b100 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
2b110 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
2b120 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
2b130 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2b140 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
2b150 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
2b160 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2b170 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
2b180 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
2b190 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
2b1a0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
2b1b0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2b1c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
2b1d0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
2b1e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
2b1f0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2b200 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
2b210 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
2b220 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
2b230 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
2b240 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2b250 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
2b260 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2b270 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
2b280 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2b290 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2b2a0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
2b2b0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
2b2c0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
2b2d0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
2b2e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2b2f0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
2b300 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
2b310 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
2b320 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
2b330 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2b340 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2b350 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2b360 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2b370 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
2b380 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
2b390 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
2b3a0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
2b3b0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
2b3c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2b3d0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2b3e0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
2b3f0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2b400 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
2b410 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2b420 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
2b430 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
2b440 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
2b450 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2b460 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
2b470 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
2b480 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2b490 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
2b4a0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2b4b0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
2b4c0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
2b4d0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
2b4e0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
2b4f0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
2b500 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74  ment.  If [sqlit
2b510 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b520 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76   or.** the equiv
2b530 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61  alent tries to a
2b540 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f  llocate space fo
2b550 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73  r more than this
2b560 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a   many opcodes.**
2b570 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65   in a single pre
2b580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
2b590 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d   an SQLITE_NOMEM
2b5a0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2b5b0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
2b5c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2b5d0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
2b5e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2b5f0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
2b600 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2b610 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2b620 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
2b630 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
2b640 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2b650 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
2b660 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b670 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
2b680 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2b690 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
2b6a0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
2b6b0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
2b6c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
2b6d0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
2b6e0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
2b6f0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
2b700 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2b710 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
2b720 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2b730 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
2b740 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
2b750 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
2b760 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
2b770 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
2b780 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2b790 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2b7a0 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
2b7b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2b7c0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
2b7d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2b7e0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
2b7f0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
2b800 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
2b810 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
2b820 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
2b830 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
2b840 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2b850 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
2b860 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2b870 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
2b880 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
2b890 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
2b8a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2b8b0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2b8c0 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
2b8d0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2b8e0 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
2b8f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2b900 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
2b910 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
2b920 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
2b930 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2b940 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
2b950 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
2b960 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
2b970 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2b980 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2b990 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
2b9a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
2b9b0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
2b9c0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
2b9d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
2b9e0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
2b9f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2ba00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
2ba10 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
2ba20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
2ba30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2ba40 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
2ba50 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
2ba60 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2ba70 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
2ba80 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
2ba90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2baa0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
2bab0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
2bac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2bad0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
2bae0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
2baf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2bb00 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2bb10 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
2bb20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2bb30 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2bb40 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
2bb50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bb60 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2bb70 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
2bb80 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2bb90 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
2bba0 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
2bbb0 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
2bbc0 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67  EF: Prepare Flag
2bbd0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
2bbe0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
2bbf0 61 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61  arious flags tha
2bc00 74 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  t can be passed 
2bc10 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61  into.** "prepFla
2bc20 67 73 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66  gs" parameter of
2bc30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
2bc40 65 70 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a  epare_v3()] and.
2bc50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2bc60 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65  are16_v3()] inte
2bc70 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  rfaces..**.** Ne
2bc80 77 20 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61  w flags may be a
2bc90 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
2bca0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
2bcb0 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  e..**.** <dl>.**
2bcc0 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52   [[SQLITE_PREPAR
2bcd0 45 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e  E_PERSISTENT]] ^
2bce0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50  (<dt>SQLITE_PREP
2bcf0 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f  ARE_PERSISTENT</
2bd00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53  dt>.** <dd>The S
2bd10 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2bd20 52 53 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73  RSISTENT flag is
2bd30 20 61 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71   a hint to the q
2bd40 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20  uery planner.** 
2bd50 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
2bd60 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  d statement will
2bd70 20 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72   be retained for
2bd80 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64   a long time and
2bd90 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75  .** probably reu
2bda0 73 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29  sed many times.)
2bdb0 5e 20 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20  ^ ^Without this 
2bdc0 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70  flag, [sqlite3_p
2bdd0 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20  repare_v3()].** 
2bde0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2bdf0 70 61 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73  pare16_v3()] ass
2be00 75 6d 65 20 74 68 61 74 20 74 68 65 20 70 72 65  ume that the pre
2be10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2be20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64  will .** be used
2be30 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74   just once or at
2be40 20 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65   most a few time
2be50 73 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72  s and then destr
2be60 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  oyed using.** [s
2be70 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2be80 29 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f  )] relatively so
2be90 6f 6e 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20  on. The current 
2bea0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61  implementation a
2beb0 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68  cts.** on this h
2bec0 69 6e 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20  int by avoiding 
2bed0 74 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b  the use of [look
2bee0 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f  aside memory] so
2bef0 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65   as not to.** de
2bf00 70 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65  plete the limite
2bf10 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61  d store of looka
2bf20 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74  side memory. Fut
2bf30 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a  ure versions of.
2bf40 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63  ** SQLite may ac
2bf50 74 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64  t on this hint d
2bf60 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c  ifferently..** <
2bf70 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
2bf80 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2bf90 45 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20  ERSISTENT       
2bfa0 20 20 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a         0x01../*.
2bfb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
2bfc0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
2bfd0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
2bfe0 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
2bff0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
2c000 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2c010 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
2c020 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c030 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
2c040 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
2c050 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
2c060 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
2c070 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
2c080 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
2c090 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2c0a0 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65  es.  Or, in othe
2c0b0 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72  r words, these r
2c0c0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63  outines.** are c
2c0d0 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  onstructors for 
2c0e0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c0f0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e  atement] object.
2c100 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65  .**.** The prefe
2c110 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20  rred routine to 
2c120 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f  use is [sqlite3_
2c130 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20  prepare_v2()].  
2c140 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2c150 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72  prepare()] inter
2c160 66 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61  face is legacy a
2c170 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  nd should be avo
2c180 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65  ided..** [sqlite
2c190 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
2c1a0 68 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72  has an extra "pr
2c1b0 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20  epFlags" option 
2c1c0 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20  that is used.** 
2c1d0 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70  for special purp
2c1e0 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  oses..**.** The 
2c1f0 75 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38  use of the UTF-8
2c200 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70   interfaces is p
2c210 72 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c  referred, as SQL
2c220 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  ite currently.**
2c230 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e   does all parsin
2c240 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20  g using UTF-8.  
2c250 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72  The UTF-16 inter
2c260 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
2c270 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65  ed.** as a conve
2c280 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46  nience.  The UTF
2c290 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77  -16 interfaces w
2c2a0 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e  ork by convertin
2c2b0 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74  g the.** input t
2c2c0 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20  ext into UTF-8, 
2c2d0 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68  then invoking th
2c2e0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2c2f0 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e  UTF-8 interface.
2c300 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2c310 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
2c320 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
2c330 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
2c340 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
2c350 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
2c360 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2c370 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2c380 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
2c390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2c3a0 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
2c3b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c3c0 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
2c3d0 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
2c3e0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
2c3f0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
2c400 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
2c410 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
2c420 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
2c430 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
2c440 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
2c450 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71  e3_prepare(), sq
2c460 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c470 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2c480 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a  e3_prepare_v3().
2c490 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
2c4a0 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
2c4b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2c4c0 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2c4d0 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64  e16_v2(),.** and
2c4e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c4f0 31 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d  16_v3() use UTF-
2c500 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
2c510 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
2c520 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2c530 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
2c540 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
2c550 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2c560 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
2c570 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
2c580 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
2c590 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
2c5a0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
2c5b0 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
2c5c0 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
2c5d0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2c5e0 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
2c5f0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
2c600 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
2c610 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
2c620 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
2c630 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
2c640 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
2c650 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
2c660 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
2c670 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
2c680 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
2c690 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2c6a0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
2c6b0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
2c6c0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
2c6d0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
2c6e0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
2c6f0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
2c700 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
2c710 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
2c720 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
2c730 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
2c740 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
2c750 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
2c760 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
2c770 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
2c780 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
2c790 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
2c7a0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2c7b0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
2c7c0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
2c7d0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
2c7e0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2c7f0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
2c800 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c810 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
2c820 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
2c830 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
2c840 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
2c850 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
2c860 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
2c870 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
2c880 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
2c890 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
2c8a0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
2c8b0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
2c8c0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
2c8d0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
2c8e0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
2c8f0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
2c900 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
2c910 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
2c920 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
2c930 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
2c940 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2c950 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
2c960 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2c970 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
2c980 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
2c990 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
2c9a0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
2c9b0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
2c9c0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
2c9d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2c9e0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
2c9f0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2ca00 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2ca10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
2ca20 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69  epare_v2(), sqli
2ca30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2ca40 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2ca50 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64  e16_v2(),.** and
2ca60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2ca70 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63  16_v3() interfac
2ca80 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64  es are recommend
2ca90 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
2caa0 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20  rograms..** The 
2cab0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
2cac0 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   (sqlite3_prepar
2cad0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2cae0 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20  prepare16()).** 
2caf0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
2cb00 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
2cb10 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
2cb20 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
2cb30 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
2cb40 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
2cb50 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
2cb60 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
2cb70 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
2cb80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2cb90 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
2cba0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
2cbb0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
2cbc0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
2cbd0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
2cbe0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
2cbf0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
2cc00 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
2cc10 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
2cc20 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
2cc30 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2cc40 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
2cc50 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
2cc60 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
2cc70 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
2cc80 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
2cc90 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
2cca0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
2ccb0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2ccc0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
2ccd0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
2cce0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
2ccf0 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
2cd00 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
2cd10 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
2cd20 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
2cd30 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2cd40 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
2cd50 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
2cd60 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2cd70 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
2cd80 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
2cd90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
2cda0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
2cdb0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
2cdc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
2cdd0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
2cde0 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
2cdf0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
2ce00 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
2ce10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
2ce20 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
2ce30 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
2ce40 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
2ce50 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
2ce60 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
2ce70 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
2ce80 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
2ce90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2cea0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
2ceb0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
2cec0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
2ced0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
2cee0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
2cef0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
2cf00 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
2cf10 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
2cf20 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
2cf30 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
2cf40 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
2cf50 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
2cf60 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
2cf70 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
2cf80 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
2cf90 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
2cfa0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
2cfb0 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
2cfc0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2cfd0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
2cfe0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
2cff0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
2d000 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
2d010 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
2d020 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
2d030 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
2d040 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
2d050 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
2d060 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
2d070 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
2d080 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2d090 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
2d0a0 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
2d0b0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
2d0c0 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
2d0d0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
2d0e0 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
2d0f0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2d100 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
2d110 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
2d120 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2d130 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
2d140 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
2d150 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
2d160 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
2d170 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
2d180 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
2d190 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
2d1a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
2d1b0 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
2d1c0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
2d1d0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
2d1e0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  li>.** </ol>.**.
2d1f0 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70  ** <p>^sqlite3_p
2d200 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66 66  repare_v3() diff
2d210 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ers from sqlite3
2d220 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e  _prepare_v2() on
2d230 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20  ly in having.** 
2d240 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46 6c  the extra prepFl
2d250 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77  ags parameter, w
2d260 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61 72  hich is a bit ar
2d270 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f  ray consisting o
2d280 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  f zero or.** mor
2d290 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
2d2a0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2d2b0 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41  ENT|SQLITE_PREPA
2d2c0 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54  RE_*] flags.  ^T
2d2d0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
2d2e0 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72  epare_v2() inter
2d2f0 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74  face works exact
2d300 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ly the same as.*
2d310 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2d320 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a 65  e_v3() with a ze
2d330 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ro prepFlags par
2d340 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  ameter..*/.int s
2d350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
2d360 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2d370 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2d380 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2d390 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2d3a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2d3b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2d3c0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2d3d0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2d3e0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2d3f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2d400 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2d410 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2d420 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2d430 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2d440 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2d450 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2d460 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2d470 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2d480 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2d490 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2d4a0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
2d4b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2d4c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2d4d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2d4e0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2d4f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2d500 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2d510 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2d520 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2d530 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2d540 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2d550 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2d560 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2d570 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2d580 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2d590 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2d5a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2d5b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2d5c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2d5d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2d5e0 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71  prepare_v3(.  sq
2d5f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2d600 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2d610 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2d620 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2d630 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2d640 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2d650 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2d660 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2d670 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2d680 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2d690 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69  bytes. */.  unsi
2d6a0 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61  gned int prepFla
2d6b0 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d  gs, /* Zero or m
2d6c0 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ore SQLITE_PREPA
2d6d0 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73  RE_ flags */.  s
2d6e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2d6f0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2d700 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2d710 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2d720 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2d730 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2d740 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2d750 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2d760 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d770 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2d780 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2d790 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2d7a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2d7b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2d7c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2d7d0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2d7e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2d7f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2d800 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2d810 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2d820 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2d830 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2d840 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2d850 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2d860 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2d870 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2d880 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2d890 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2d8a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2d8b0 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
2d8c0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2d8d0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2d8e0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2d8f0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2d900 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2d910 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2d920 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2d930 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2d940 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2d950 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2d960 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2d970 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2d980 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2d990 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2d9a0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2d9b0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2d9c0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2d9d0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2d9e0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2d9f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2da00 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v3(.  sqlite3 
2da10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2da20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2da30 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2da40 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2da50 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2da60 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2da70 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2da80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2da90 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2daa0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2dab0 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20  . */.  unsigned 
2dac0 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f  int prepFlags, /
2dad0 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53  * Zero or more S
2dae0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66  QLITE_PREPARE_ f
2daf0 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65  lags */.  sqlite
2db00 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2db10 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2db20 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2db30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2db40 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2db50 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2db60 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2db70 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
2db80 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
2db90 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
2dba0 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  L.** METHOD: sql
2dbb0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2dbc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c  ^The sqlite3_sql
2dbd0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2dbe0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2dbf0 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  to a copy of the
2dc00 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65   UTF-8.** SQL te
2dc10 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
2dc20 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2dc30 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61  ement] P if P wa
2dc40 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
2dc50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2dc60 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2dc70 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a  _prepare_v3()],.
2dc80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2dc90 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20  are16_v2()], or 
2dca0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2dcb0 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68  16_v3()]..** ^Th
2dcc0 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2dcd0 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2dce0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2dcf0 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2dd00 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2dd10 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  ining the SQL te
2dd20 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73  xt of prepared s
2dd30 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a  tatement P with.
2dd40 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  ** [bound parame
2dd50 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a  ters] expanded..
2dd60 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2dd70 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72  ple, if a prepar
2dd80 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2dd90 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
2dda0 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53  e SQL.** text "S
2ddb0 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2ddc0 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65   and if paramete
2ddd0 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20  r $abc is bound 
2dde0 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a  to integer 2345.
2ddf0 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72  ** and parameter
2de00 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64   :xyz is unbound
2de10 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  , then sqlite3_s
2de20 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ql() will return
2de30 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
2de40 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54   string, "SELECT
2de50 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20   $abc,:xyz" but 
2de60 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2de70 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72  _sql().** will r
2de80 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33  eturn "SELECT 23
2de90 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a  45,NULL".)^.**.*
2dea0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2deb0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e  xpanded_sql() in
2dec0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2ded0 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
2dee0 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  ient memory.** i
2def0 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68  s available to h
2df00 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20  old the result, 
2df10 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74  or if the result
2df20 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2df30 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d  e.** the maximum
2df40 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64   string length d
2df50 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2df60 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c   [SQLITE_LIMIT_L
2df70 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ENGTH]..**.** ^T
2df80 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
2df90 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
2dfa0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2dfb0 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
2dfc0 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72   of.** bound par
2dfd0 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e  ameter expansion
2dfe0 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  s.  ^The [SQLITE
2dff0 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d  _OMIT_TRACE] com
2e000 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
2e010 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74  ion causes sqlit
2e020 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2e030 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75  ) to always retu
2e040 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  rn NULL..**.** ^
2e050 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2e060 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  ned by sqlite3_s
2e070 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64  ql(P) is managed
2e080 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69   by SQLite and i
2e090 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2e0a0 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68  ly freed when th
2e0b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2e0c0 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2e0d0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2e0e0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2e0f0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2e100 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2e110 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2e120 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2e130 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2e140 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2e150 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2e160 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2e170 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2e180 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  3_free()]..*/.co
2e190 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2e1a0 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
2e1b0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72  mt *pStmt);.char
2e1c0 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2e1d0 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2e1e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2e1f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2e200 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
2e210 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
2e220 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
2e230 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e240 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2e250 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2e260 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
2e270 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2e280 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2e290 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
2e2a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2e2b0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
2e2c0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
2e2d0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
2e2e0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2e2f0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
2e300 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
2e310 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
2e330 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
2e340 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
2e350 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2e360 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
2e370 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
2e380 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2e390 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
2e3a0 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
2e3b0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
2e3c0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
2e3d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
2e3e0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
2e3f0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
2e400 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
2e410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2e420 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
2e430 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
2e440 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2e450 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
2e460 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
2e470 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
2e480 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
2e490 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
2e4a0 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
2e4b0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
2e4c0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2e4d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
2e4e0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
2e4f0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2e500 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
2e510 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
2e520 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
2e530 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
2e540 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
2e550 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
2e560 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
2e570 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
2e580 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
2e590 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2e5a0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2e5b0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
2e5c0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
2e5d0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
2e5e0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
2e5f0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2e600 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
2e610 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
2e620 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
2e630 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
2e640 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
2e650 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
2e660 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
2e670 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
2e680 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
2e690 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2e6a0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2e6b0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
2e6c0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
2e6d0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
2e6e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
2e6f0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
2e700 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
2e710 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
2e720 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
2e730 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2e740 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
2e750 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  k..** ^The sqlit
2e760 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2e770 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2e780 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42  urns true for [B
2e790 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b  EGIN] since.** [
2e7a0 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65  BEGIN] merely se
2e7b0 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67  ts internal flag
2e7c0 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49  s, but the [BEGI
2e7d0 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54  N|BEGIN IMMEDIAT
2e7e0 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e  E] and.** [BEGIN
2e7f0 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45  |BEGIN EXCLUSIVE
2e800 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f  ] commands do to
2e810 75 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  uch the database
2e820 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74   and so.** sqlit
2e830 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2e840 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  () returns false
2e850 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61   for those comma
2e860 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
2e870 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2e880 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
2e890 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2e8a0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2e8b0 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
2e8c0 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
2e8d0 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54  een Reset.** MET
2e8e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e8f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2e900 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2e910 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e920 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2e930 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
2e940 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e950 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
2e960 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
2e970 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
2e980 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2e990 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20  but has neither 
2e9a0 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
2e9b0 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  n (returned.** [
2e9c0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f  SQLITE_DONE] fro
2e9d0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  m [sqlite3_step(
2e9e0 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e  S)]) nor.** been
2e9f0 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
2ea00 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
2ea10 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
2ea20 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
2ea30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2ea40 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
2ea50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
2ea60 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
2ea70 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
2ea80 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
2ea90 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
2eaa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2eab0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
2eac0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2ead0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2eae0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
2eaf0 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
2eb00 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2eb10 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
2eb20 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
2eb30 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
2eb40 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
2eb50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2eb60 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
2eb70 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
2eb80 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
2eb90 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
2eba0 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
2ebb0 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
2ebc0 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
2ebd0 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
2ebe0 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
2ebf0 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
2ec00 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
2ec10 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
2ec20 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
2ec30 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
2ec40 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
2ec50 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2ec60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
2ec70 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
2ec80 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
2ec90 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
2eca0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2ecb0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
2ecc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
2ecd0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
2ece0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
2ecf0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
2ed00 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
2ed10 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
2ed20 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
2ed30 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
2ed40 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2ed50 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
2ed60 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
2ed70 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
2ed80 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
2ed90 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
2eda0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
2edb0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
2edc0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
2edd0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
2ede0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
2edf0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2ee00 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
2ee10 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
2ee20 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
2ee30 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
2ee40 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
2ee50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ee60 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
2ee70 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
2ee80 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
2ee90 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
2eea0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2eeb0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
2eec0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
2eed0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
2eee0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
2eef0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
2ef00 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
2ef10 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
2ef20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ef30 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
2ef40 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20  e3_value_dup()] 
2ef50 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2ef60 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75   used to constru
2ef70 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f  ct a new .** pro
2ef80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ef90 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70  alue from an unp
2efa0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2efb0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
2efc0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
2efd0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
2efe0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
2eff0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
2f000 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
2f010 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
2f020 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2f030 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
2f040 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2f050 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
2f060 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
2f070 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2f080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2f090 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
2f0a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
2f0b0 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
2f0c0 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
2f0d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
2f0e0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
2f0f0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2f100 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
2f110 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
2f120 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
2f130 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
2f140 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
2f150 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
2f160 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
2f170 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2f180 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
2f190 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
2f1a0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2f1b0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2f1c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2f1d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
2f1e0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
2f1f0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
2f200 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
2f210 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
2f220 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
2f230 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
2f240 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
2f250 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
2f260 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
2f270 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2f280 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2f290 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2f2a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
2f2b0 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
2f2c0 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
2f2d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f2e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
2f2f0 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
2f300 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
2f310 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
2f320 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
2f330 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f340 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
2f350 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
2f360 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2f370 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
2f380 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2f390 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2f3a0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
2f3b0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
2f3c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f3d0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
2f3e0 62 65 20 75 73 65 64 20 61 73 20 61 72 67 75 6d  be used as argum
2f3f0 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ents.** to [sqli
2f400 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2f410 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69  ()], [sqlite3_bi
2f420 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64  nd_value()], and
2f430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2f440 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68  ue_dup()]..** Th
2f450 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2f460 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2f470 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
2f480 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
2f490 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
2f4a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2f4b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
2f4c0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2f4d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73   sqlite3_value s
2f4e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
2f4f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2f500 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
2f510 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
2f520 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
2f530 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
2f540 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
2f550 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
2f560 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
2f570 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
2f580 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
2f590 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2f5a0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
2f5b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2f5c0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
2f5d0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2f5e0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
2f5f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f600 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2f610 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2f620 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
2f630 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
2f640 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
2f650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2f660 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
2f670 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
2f680 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f690 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
2f6a0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
2f6b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
2f6c0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2f6d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
2f6e0 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
2f6f0 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
2f700 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
2f710 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2f720 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2f730 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2f740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f750 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
2f760 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
2f770 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
2f780 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
2f790 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
2f7a0 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
2f7b0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
2f7c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
2f7d0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
2f7e0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
2f7f0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
2f800 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2f810 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2f820 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
2f830 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
2f840 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
2f850 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
2f860 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
2f870 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
2f880 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
2f890 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
2f8a0 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
2f8b0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
2f8c0 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
2f8d0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
2f8e0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
2f8f0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
2f900 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
2f910 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
2f920 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
2f930 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
2f940 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
2f950 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
2f960 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
2f970 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
2f980 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
2f990 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
2f9a0 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
2f9b0 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
2f9c0 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
2f9d0 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
2f9e0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
2f9f0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
2fa00 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2fa10 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2fa20 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
2fa30 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2fa40 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2fa50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2fa60 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
2fa70 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
2fa80 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2fa90 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
2faa0 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
2fab0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2fac0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
2fad0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
2fae0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2faf0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2fb00 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
2fb10 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
2fb20 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
2fb30 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
2fb40 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
2fb50 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
2fb60 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
2fb70 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
2fb80 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
2fb90 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2fba0 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
2fbb0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
2fbc0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
2fbd0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
2fbe0 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
2fbf0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
2fc00 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
2fc10 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
2fc20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2fc30 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2fc40 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
2fc50 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
2fc60 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
2fc70 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
2fc80 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
2fc90 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
2fca0 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
2fcb0 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
2fcc0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
2fcd0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
2fce0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2fcf0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
2fd00 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
2fd10 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2fd20 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
2fd30 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
2fd40 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
2fd50 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2fd60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2fd70 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2fd80 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2fd90 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20  _text16().** or 
2fda0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2fdb0 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  b() is a NULL po
2fdc0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66  inter then the f
2fdd0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a  ourth parameter.
2fde0 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e  ** is ignored an
2fdf0 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74  d the end result
2fe00 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
2fe10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2fe20 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  l()..**.** ^(In 
2fe30 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
2fe40 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
2fe50 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
2fe60 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2fe70 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2fe80 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2fe90 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
2fea0 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
2feb0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
2fec0 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
2fed0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
2fee0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2fef0 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
2ff00 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2ff10 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2ff20 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2ff30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ff40 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
2ff50 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
2ff60 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
2ff70 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
2ff80 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
2ff90 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2ffa0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2ffb0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
2ffc0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2ffd0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2ffe0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2fff0 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
30000 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
30010 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
30020 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
30030 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
30040 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
30050 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
30060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
30070 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  16() or sqlite3_
30080 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68  bind_text64() th
30090 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d  en.** that param
300a0 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
300b0 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
300c0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
300d0 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
300e0 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
300f0 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
30100 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
30110 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
30120 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
30130 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
30140 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
30150 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
30160 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
30170 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
30180 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
30190 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
301a0 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
301b0 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
301c0 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
301d0 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
301e0 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
301f0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
30200 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
30210 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42  rgument to the B
30220 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62  LOB and string b
30230 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65  inding interface
30240 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75  s.** is a destru
30250 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
30260 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
30270 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
30280 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
30290 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
302a0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
302b0 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
302c0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
302d0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
302e0 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
302f0 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69   to bind API fai
30300 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ls..** ^If the f
30310 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
30320 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
30330 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
30340 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
30350 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
30360 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
30370 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
30380 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
30390 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
303a0 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
303b0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
303c0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
303d0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
303e0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
303f0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
30400 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
30410 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
30420 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
30430 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
30440 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
30450 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
30460 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20  *.** ^The sixth 
30470 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
30480 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
30490 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
304a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
304b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
304c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
304d0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
304e0 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73  UTF16LE].** to s
304f0 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64  pecify the encod
30500 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20  ing of the text 
30510 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
30520 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74  ameter.  If.** t
30530 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
30540 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
30550 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f  d_text64() is no
30560 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
30570 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73  allowed values s
30580 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69  hown above, or i
30590 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  f the text encod
305a0 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
305b0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63  .** from the enc
305c0 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20  oding specified 
305d0 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72  by the sixth par
305e0 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
305f0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
30600 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
30610 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
30620 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
30630 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
30640 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
30650 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
30660 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
30670 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
30680 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
30690 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
306a0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
306b0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
306c0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
306d0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
306e0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
306f0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
30700 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
30710 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
30720 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
30730 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
30740 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
30750 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
30760 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
30770 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
30780 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
30790 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
307a0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
307b0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
307c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
307d0 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c  _bind_pointer(S,
307e0 49 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65  I,P,T,D) routine
307f0 20 63 61 75 73 65 73 20 74 68 65 20 49 2d 74 68   causes the I-th
30800 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a   parameter in.**
30810 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30820 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20  ment] S to have 
30830 61 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20  an SQL value of 
30840 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73  NULL, but to als
30850 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74  o be.** associat
30860 65 64 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e  ed with the poin
30870 74 65 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e  ter P of type T.
30880 20 20 5e 44 20 69 73 20 65 69 74 68 65 72 20 61    ^D is either a
30890 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
308a0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
308b0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75   a destructor fu
308c0 6e 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53  nction for P. ^S
308d0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
308e0 65 20 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63  e the.** destruc
308f0 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e  tor D with a sin
30900 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
30910 50 20 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e  P when it is fin
30920 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50  ished using.** P
30930 2e 20 20 54 68 65 20 54 20 70 61 72 61 6d 65 74  .  The T paramet
30940 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73  er should be a s
30950 74 61 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72  tatic string, pr
30960 65 66 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e  eferably a strin
30970 67 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68  g.** literal. Th
30980 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
30990 6f 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65  ointer() routine
309a0 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   is part of the.
309b0 2a 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73  ** [pointer pass
309c0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61  ing interface] a
309d0 64 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20  dded for SQLite 
309e0 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49  3.20.0..**.** ^I
309f0 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
30a00 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
30a10 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
30a20 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
30a30 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
30a40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30a50 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
30a60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30a70 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
30a80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
30a90 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
30aa0 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
30ab0 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
30ac0 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
30ad0 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
30ae0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
30af0 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
30b00 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
30b10 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
30b20 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
30b30 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
30b40 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
30b50 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
30b60 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
30b70 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
30b80 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
30b90 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
30ba0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
30bb0 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
30bc0 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
30bd0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
30be0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
30bf0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
30c00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
30c10 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
30c20 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
30c30 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
30c40 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
30c50 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
30c60 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
30c70 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65  TOOBIG] might be
30c80 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
30c90 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e   size of a strin
30ca0 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63  g or BLOB.** exc
30cb0 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f  eeds limits impo
30cc0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
30cd0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
30ce0 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72  IMIT_LENGTH]) or
30cf0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
30d00 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51  LENGTH]..** ^[SQ
30d10 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
30d20 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
30d30 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
30d40 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
30d50 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
30d60 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
30d70 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
30d80 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
30d90 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
30da0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
30db0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
30dc0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30dd0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
30de0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30df0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
30e00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
30e10 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
30e20 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
30e30 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
30e40 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
30e50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30e60 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
30e70 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
30e80 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
30e90 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
30ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30eb0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
30ec0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
30ed0 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
30ee0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
30ef0 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
30f00 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
30f10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30f20 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
30f30 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
30f40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30f50 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
30f60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
30f70 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
30f80 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
30f90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
30fa0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
30fb0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
30fc0 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69  ,int,void(*)(voi
30fd0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
30fe0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
30ff0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31000 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
31010 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
31020 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
31030 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c  _bind_text64(sql
31040 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
31050 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
31060 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
31070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31080 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
31090 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20  oid*), unsigned 
310a0 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a  char encoding);.
310b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
310c0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
310d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
310e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
310f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
31100 6e 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74  nd_pointer(sqlit
31110 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76  e3_stmt*, int, v
31120 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
31130 2a 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  *,void(*)(void*)
31140 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
31150 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
31160 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
31170 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c   int n);.int sql
31180 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
31190 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
311a0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
311b0 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  _uint64);../*.**
311c0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
311d0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
311e0 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ers.** METHOD: s
311f0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31200 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
31210 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
31220 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
31230 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
31240 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
31250 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
31260 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
31270 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
31280 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
31290 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
312a0 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
312b0 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
312c0 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
312d0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
312e0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
312f0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
31300 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
31310 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
31320 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
31330 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
31340 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
31350 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
31360 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
31370 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
31380 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
31390 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
313a0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
313b0 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
313c0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
313d0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
313e0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
313f0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
31400 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
31410 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
31420 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
31430 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
31440 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
31450 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
31460 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
31470 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
31480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
31490 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
314a0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
314b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
314c0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
314d0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
314e0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
314f0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
31500 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  er.** METHOD: sq
31510 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31520 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
31530 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
31540 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
31550 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
31560 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
31570 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
31580 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
31590 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
315a0 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
315b0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
315c0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
315d0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
315e0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
315f0 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
31600 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
31610 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
31620 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
31630 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
31640 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
31650 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
31660 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
31670 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
31680 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
31690 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
316a0 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
316b0 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
316c0 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
316d0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
316e0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
316f0 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
31700 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
31710 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
31720 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
31730 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
31740 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
31750 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
31760 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
31770 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
31780 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
31790 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
317a0 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
317b0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
317c0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
317d0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
317e0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
317f0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
31800 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
31810 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
31820 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
31830 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
31840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
31850 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
31860 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
31870 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
31880 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
31890 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
318a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
318b0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
318c0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
318d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
318e0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
318f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
31900 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
31910 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
31920 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
31930 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
31940 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
31950 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31960 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
31970 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
31980 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48  ven Name.** METH
31990 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
319a0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
319b0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
319c0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
319d0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
319e0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
319f0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
31a00 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
31a10 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
31a20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
31a30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
31a40 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
31a50 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
31a60 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
31a70 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
31a80 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
31a90 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
31aa0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
31ab0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
31ac0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
31ad0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
31ae0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
31af0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
31b00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31b10 65 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  e16_v2()] or.** 
31b20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31b30 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v3()]..**.** 
31b40 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
31b50 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
31b60 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
31b70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
31b80 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
31b90 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
31ba0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
31bb0 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  r_name()]..*/.in
31bc0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
31bd0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
31be0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
31bf0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
31c00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31c10 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
31c20 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
31c30 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
31c40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31c50 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  _stmt.**.** ^Con
31c60 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
31c70 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
31c80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31c90 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
31ca0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
31cb0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
31cc0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
31cd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31ce0 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
31cf0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
31d00 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
31d10 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
31d20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
31d30 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
31d40 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
31d50 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
31d60 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
31d70 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
31d80 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31d90 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
31da0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
31db0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
31dc0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
31dd0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
31de0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31df0 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f  nt]. ^If this ro
31e00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c  utine returns 0,
31e10 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
31e20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
31e30 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73  atement] returns
31e40 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78   no data (for ex
31e50 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
31e60 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c  ])..** ^However,
31e70 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 74 68   just because th
31e80 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
31e90 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75  ns a positive nu
31ea0 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  mber does not.**
31eb0 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f   mean that one o
31ec0 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64  r more rows of d
31ed0 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75  ata will be retu
31ee0 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54  rned.  ^A SELECT
31ef0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69   statement.** wi
31f00 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20 61  ll always have a
31f10 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65   positive sqlite
31f20 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
31f30 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f   but depending o
31f40 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63  n the.** WHERE c
31f50 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
31f60 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20  s and the table 
31f70 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68  content, it migh
31f80 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73  t return no rows
31f90 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
31fa0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
31fb0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
31fc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
31fd0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
31fe0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
31ff0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
32000 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
32010 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
32020 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
32030 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
32040 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
32050 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
32060 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
32070 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
32080 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
32090 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
320a0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
320b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
320c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
320d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
320e0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
320f0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
32100 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
32110 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
32120 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
32130 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
32140 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
32150 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
32160 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
32170 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
32180 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
32190 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
321a0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
321b0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
321c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
321d0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
321e0 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
321f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
32200 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
32210 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
32220 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
32230 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
32240 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
32250 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
32260 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
32270 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
32280 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
32290 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
322a0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
322b0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
322c0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
322d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
322e0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
322f0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
32300 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
32310 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
32320 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
32330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
32340 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
32350 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
32360 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
32370 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
32380 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
32390 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
323a0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
323b0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
323c0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
323d0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
323e0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
323f0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
32400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
32410 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
32420 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
32430 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
32440 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
32450 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
32460 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
32470 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
32480 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
32490 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
324a0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
324b0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
324c0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
324d0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
324e0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
324f0 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
32500 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
32510 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
32520 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
32530 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
32540 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
32550 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32560 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
32570 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
32580 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
32590 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
325a0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
325b0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
325c0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
325d0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
325e0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
325f0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
32600 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
32610 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
32620 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
32630 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
32640 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
32650 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
32660 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
32670 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
32680 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
32690 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
326a0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
326b0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
326c0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
326d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
326e0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
326f0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
32700 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
32710 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
32720 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
32730 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
32740 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
32750 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
32760 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
32770 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
32780 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32790 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
327a0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
327b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
327c0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
327d0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
327e0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
327f0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
32800 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
32810 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
32820 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
32830 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
32840 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
32850 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
32860 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
32870 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
32880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
32890 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
328a0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
328b0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
328c0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
328d0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
328e0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
328f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
32900 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
32910 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
32920 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
32930 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
32940 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
32950 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
32960 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
32970 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
32980 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
32990 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
329a0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
329b0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
329c0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
329d0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
329e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
329f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
32a00 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
32a10 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
32a20 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
32a30 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
32a40 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
32a50 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
32a60 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
32a70 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
32a80 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
32a90 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
32aa0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
32ab0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
32ac0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
32ad0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
32ae0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
32af0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
32b00 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
32b10 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
32b20 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
32b30 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
32b40 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
32b50 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
32b60 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
32b70 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
32b80 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
32b90 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
32ba0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
32bb0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
32bc0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
32bd0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
32be0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
32bf0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
32c00 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
32c10 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
32c20 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
32c30 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
32c40 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
32c50 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
32c60 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
32c70 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
32c80 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
32c90 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
32ca0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
32cb0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
32cc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
32cd0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
32ce0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
32cf0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
32d00 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
32d10 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
32d20 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
32d30 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
32d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
32d50 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
32d60 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
32d70 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
32d80 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
32d90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
32da0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
32db0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
32dc0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
32dd0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
32de0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
32df0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
32e00 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
32e10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32e20 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
32e30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
32e40 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
32e50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32e60 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
32e70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32e80 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
32e90 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
32ea0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32eb0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
32ec0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
32ed0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
32ee0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
32ef0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
32f00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32f10 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
32f20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
32f30 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
32f40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
32f50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32f60 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
32f70 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
32f80 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
32f90 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
32fa0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
32fb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
32fc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32fd0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
32fe0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
32ff0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
33000 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
33010 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
33020 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
33030 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
33040 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
33050 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
33060 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
33070 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
33080 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
33090 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
330a0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
330b0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
330c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
330d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
330e0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
330f0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
33100 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
33110 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
33120 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
33130 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
33140 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
33150 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
33160 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
33170 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
33180 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
33190 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
331a0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
331b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
331c0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
331d0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
331e0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
331f0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
33200 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
33210 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
33220 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
33230 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
33240 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
33250 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
33260 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
33270 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
33280 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
33290 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
332a0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
332b0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
332c0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
332d0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
332e0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
332f0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
33300 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
33310 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
33320 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
33330 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
33340 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
33350 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
33360 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
33370 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
33380 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
33390 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
333a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
333b0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
333c0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
333d0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
333e0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
333f0 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
33400 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
33410 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
33420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
33430 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
33440 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
33450 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
33460 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
33470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
33480 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
33490 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
334a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
334b0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
334c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
334d0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
334e0 72 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66  red using any of
334f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
33500 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
33510 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
33520 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
33530 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a  pare16_v2()],.**
33540 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
33550 70 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20  pare16_v3()] or 
33560 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
33570 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
33580 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33590 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
335a0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
335b0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
335c0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
335d0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
335e0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
335f0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
33600 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
33610 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
33620 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
33630 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
33640 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
33650 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
33660 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
33670 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 58  ng the newer "vX
33680 22 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  " interfaces.** 
33690 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
336a0 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
336b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
336c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
336d0 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71  16_v3()],.** [sq
336e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
336f0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
33700 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
33710 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
33720 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
33730 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33740 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
33750 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
33760 58 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  X" interface is 
33770 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
33780 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
33790 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
337a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
337b0 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
337c0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
337d0 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79  * ^In the legacy
337e0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
337f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
33800 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
33810 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
33820 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
33830 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
33840 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
33850 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
33860 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22  * ^With the "v2"
33870 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
33880 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
33890 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
338a0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
338b0 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
338c0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
338d0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ell..**.** ^[SQL
338e0 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
338f0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
33900 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
33910 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
33920 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
33930 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
33940 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49   do its job.  ^I
33950 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
33960 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
33970 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
33980 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
33990 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
339a0 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
339b0 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
339c0 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
339d0 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
339e0 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
339f0 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20  rs within an.** 
33a00 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
33a10 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
33a20 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
33a30 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
33a40 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
33a50 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
33a60 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
33a70 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
33a80 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
33a90 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
33aa0 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
33ab0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
33ac0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
33ad0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
33ae0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
33af0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
33b00 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
33b10 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
33b20 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
33b30 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
33b40 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
33b50 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
33b60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
33b70 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
33b80 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
33b90 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
33ba0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
33bb0 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
33bc0 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
33bd0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
33be0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
33bf0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
33c00 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
33c10 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
33c20 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
33c30 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
33c40 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
33c50 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
33c60 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
33c70 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
33c80 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
33c90 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
33ca0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
33cb0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
33cc0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
33cd0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
33ce0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
33cf0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
33d00 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
33d10 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
33d20 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
33d30 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
33d40 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
33d50 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
33d60 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
33d70 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
33d80 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
33d90 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
33da0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
33db0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
33dc0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
33dd0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
33de0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
33df0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
33e00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
33e10 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
33e20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33e30 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
33e40 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
33e50 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
33e60 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
33e70 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
33e80 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
33e90 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
33ea0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
33eb0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
33ec0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
33ed0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
33ee0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
33ef0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
33f00 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
33f10 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
33f20 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
33f30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
33f40 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
33f50 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
33f60 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
33f70 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
33f80 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
33f90 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
33fa0 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
33fb0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
33fc0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
33fd0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
33fe0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
33ff0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
34000 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
34010 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
34020 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f  * For all versio
34030 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20  ns of SQLite up 
34040 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
34050 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c   3.6.23.1, a cal
34060 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
34070 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65  _reset()] was re
34080 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c  quired after sql
34090 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
340a0 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a  rned anything.**
340b0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
340c0 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20  ITE_ROW] before 
340d0 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
340e0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
340f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
34100 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65   Failure to rese
34110 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
34120 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a  tatement using .
34130 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
34140 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c  t()] would resul
34150 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
34160 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
34170 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  rom.** sqlite3_s
34180 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
34190 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  r [version 3.6.2
341a0 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e  3.1] ([dateof:3.
341b0 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69  6.23.1],.** sqli
341c0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
341d0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
341e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
341f0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
34200 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
34210 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
34220 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
34230 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
34240 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
34250 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
34260 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
34270 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
34280 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
34290 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
342a0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
342b0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
342c0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
342d0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
342e0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
342f0 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
34300 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
34310 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
34320 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
34330 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
34340 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
34350 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
34360 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
34370 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
34380 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
34390 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
343a0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
343b0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
343c0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
343d0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
343e0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
343f0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
34400 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
34410 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
34420 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
34430 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
34440 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
34450 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
34460 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
34470 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
34480 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
34490 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
344a0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
344b0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
344c0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
344d0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
344e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
344f0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
34500 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
34510 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
34520 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
34530 61 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71  are_v3()] or [sq
34540 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
34550 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
34560 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
34570 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
34580 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69  repare16_v3()] i
34590 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
345a0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
345b0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
345c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
345d0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
345e0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
345f0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
34600 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
34610 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
34620 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
34630 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
34640 66 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72  f the "vX" inter
34650 66 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65  faces is recomme
34660 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
34670 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
34680 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
34690 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
346a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
346b0 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  a result set.** 
346c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
346d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
346e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
346f0 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
34700 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
34710 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
34720 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
34730 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
34740 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
34750 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
34760 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
34770 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
34780 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
34790 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
347a0 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
347b0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
347c0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
347d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
347e0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
347f0 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
34800 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
34810 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
34820 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
34830 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
34840 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
34850 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
34860 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
34870 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
34880 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
34890 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
348a0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
348b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
348c0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
348d0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
348e0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
348f0 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
34900 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
34910 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
34920 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
34930 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
34940 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
34950 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
34960 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
34970 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
34980 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
34990 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
349a0 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
349b0 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
349c0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
349d0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
349e0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
349f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
34a00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
34a10 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
34a20 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
34a30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
34a40 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
34a50 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
34a60 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
34a70 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
34a80 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
34a90 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
34aa0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
34ab0 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
34ac0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
34ad0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
34ae0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
34af0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
34b00 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
34b10 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
34b20 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
34b30 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
34b40 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
34b50 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
34b60 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
34b70 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
34b80 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
34b90 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
34ba0 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
34bb0 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
34bc0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
34bd0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
34be0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
34bf0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
34c00 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
34c10 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
34c20 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
34c30 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
34c40 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
34c50 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
34c60 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
34c70 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
34c80 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
34c90 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
34ca0 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
34cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
34cc0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
34cd0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
34ce0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
34cf0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
34d00 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
34d10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
34d20 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
34d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
34d40 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
34d50 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
34d60 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
34d70 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
34d80 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
34d90 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
34da0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34db0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53  _stmt.**.** <b>S
34dc0 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c  ummary:</b>.** <
34dd0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c  blockquote><tabl
34de0 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70  e border=0 cellp
34df0 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61  adding=0 cellspa
34e00 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c  cing=0>.** <tr><
34e10 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34e20 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64  lumn_blob</b><td
34e30 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20  >&rarr;<td>BLOB 
34e40 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
34e50 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
34e60 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74  umn_double</b><t
34e70 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c  d>&rarr;<td>REAL
34e80 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
34e90 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34ea0 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e  lumn_int</b><td>
34eb0 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74  &rarr;<td>32-bit
34ec0 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a   INTEGER result.
34ed0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
34ee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
34ef0 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  64</b><td>&rarr;
34f00 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47  <td>64-bit INTEG
34f10 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
34f20 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34f30 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c  column_text</b><
34f40 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
34f50 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a  -8 TEXT result.*
34f60 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
34f70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
34f80 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  16</b><td>&rarr;
34f90 3c 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20  <td>UTF-16 TEXT 
34fa0 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
34fb0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
34fc0 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64  umn_value</b><td
34fd0 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72  >&rarr;<td>The r
34fe0 65 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20  esult as an .** 
34ff0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75  [sqlite3_value|u
35000 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35010 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35020 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62  ..** <tr><td>&nb
35030 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  sp;<td>&nbsp;<td
35040 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c  >&nbsp;.** <tr><
35050 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
35060 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74  lumn_bytes</b><t
35070 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65  d>&rarr;<td>Size
35080 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72   of a BLOB.** or
35090 20 61 20 55 54 46 2d 38 20 54 45 58 54 20 72 65   a UTF-8 TEXT re
350a0 73 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a  sult in bytes.**
350b0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
350c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
350d0 31 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f  16&nbsp;&nbsp;</
350e0 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b  b>.** <td>&rarr;
350f0 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e  &nbsp;&nbsp;<td>
35100 53 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a  Size of UTF-16.*
35110 2a 20 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a  * TEXT in bytes.
35120 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
35130 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
35140 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
35150 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61  td>Default.** da
35160 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65  tatype of the re
35170 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  sult.** </table>
35180 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
35190 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c  .** <b>Details:<
351a0 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  /b>.**.** ^These
351b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
351c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
351d0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
351e0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
351f0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
35200 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
35210 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
35220 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
35230 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
35240 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
35250 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
35260 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
35270 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
35280 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
35290 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
352a0 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
352b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
352c0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
352d0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
352e0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
352f0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
35300 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
35310 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
35320 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
35330 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
35340 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
35350 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
35360 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
35370 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
35380 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
35390 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
353a0 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
353b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
353c0 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
353d0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
353e0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
353f0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
35400 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
35410 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
35420 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
35430 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
35440 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
35450 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
35460 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
35470 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
35480 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
35490 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
354a0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
354b0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
354c0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
354d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
354e0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
354f0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
35500 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
35510 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
35520 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
35530 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
35540 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
35550 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
35560 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
35570 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
35580 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
35590 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
355a0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
355b0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
355c0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
355d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
355e0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
355f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
35600 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
35610 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
35620 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
35630 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
35640 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
35650 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
35660 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
35670 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
35680 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
35690 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
356a0 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 73  t six interfaces
356b0 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65   (_blob, _double
356c0 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20  , _int, _int64, 
356d0 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74  _text, and _text
356e0 31 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75  16).** each retu
356f0 72 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  rn the value of 
35700 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
35710 69 6e 20 61 20 73 70 65 63 69 66 69 63 20 64 61  in a specific da
35720 74 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a  ta format.  If.*
35730 2a 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  * the result col
35740 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69  umn is not initi
35750 61 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75  ally in the requ
35760 65 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f  ested format (fo
35770 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66  r example,.** if
35780 20 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72   the query retur
35790 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75  ns an integer bu
357a0 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  t the sqlite3_co
357b0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65  lumn_text() inte
357c0 72 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64  rface.** is used
357d0 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20   to extract the 
357e0 76 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61  value) then an a
357f0 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
35800 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
35810 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ormed..**.** ^Th
35820 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
35830 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
35840 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
35850 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
35860 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
35870 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
35880 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
35890 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
358a0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
358b0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
358c0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
358d0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
358e0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
358f0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
35900 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
35910 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65  NULL]..** The re
35920 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71  turn value of sq
35930 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
35940 65 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20  e() can be used 
35950 74 6f 20 64 65 63 69 64 65 20 77 68 69 63 68 0a  to decide which.
35960 2a 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  ** of the first 
35970 73 69 78 20 69 6e 74 65 72 66 61 63 65 20 73 68  six interface sh
35980 6f 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20  ould be used to 
35990 65 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75  extract the colu
359a0 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65  mn value..** The
359b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
359c0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
359d0 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
359e0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
359f0 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74  o.** automatic t
35a00 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
35a10 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f  have occurred fo
35a20 72 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71  r the value in q
35a30 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66  uestion.  .** Af
35a40 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
35a50 72 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c  rsion, the resul
35a60 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c  t of calling sql
35a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
35a80 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ().** is undefin
35a90 65 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c  ed, though harml
35aa0 65 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ess.  Future.** 
35ab0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
35ac0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
35ad0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
35ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
35af0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
35b00 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
35b10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
35b20 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
35b30 42 20 6f 72 20 61 20 54 45 58 54 20 73 74 72 69  B or a TEXT stri
35b40 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ng, then the sql
35b50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35b60 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  s().** or sqlite
35b70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35b80 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 63 61  () interfaces ca
35b90 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74  n be used to det
35ba0 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a  ermine the size.
35bb0 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20  ** of that BLOB 
35bc0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  or string..**.**
35bd0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
35be0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
35bf0 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
35c00 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
35c10 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
35c20 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
35c30 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
35c40 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
35c50 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
35c60 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
35c70 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
35c80 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
35c90 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
35ca0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
35cb0 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
35cc0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
35cd0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
35ce0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
35cf0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
35d00 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
35d10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
35d20 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
35d30 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
35d40 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
35d50 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
35d60 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
35d70 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
35d80 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
35d90 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
35da0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
35db0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
35dc0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35dd0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
35de0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
35df0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
35e00 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
35e10 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
35e20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35e30 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
35e40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
35e50 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
35e60 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
35e70 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
35e80 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
35e90 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
35ea0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35eb0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
35ec0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
35ed0 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
35ee0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
35ef0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
35f00 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
35f10 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
35f20 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
35f30 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
35f40 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
35f50 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
35f60 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
35f70 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
35f80 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
35f90 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
35fa0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
35fb0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
35fc0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
35fd0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
35fe0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
35ff0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
36000 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
36010 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
36020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36030 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
36040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36050 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
36060 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
36070 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
36080 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
36090 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
360a0 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
360b0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
360c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
360d0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
360e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
360f0 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
36100 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
36110 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
36120 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
36130 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
36140 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
36150 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
36160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36170 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
36180 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
36190 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
361a0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
361b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
361c0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
361d0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
361e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
361f0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
36200 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
36210 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
36220 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f  ** <b>Warning:</
36230 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  b> ^The object r
36240 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
36250 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
36260 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
36270 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36280 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
36290 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65    In a multithre
362a0 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  aded environment
362b0 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63  ,.** an unprotec
362c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
362d0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c  e object may onl
362e0 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79  y be used safely
362f0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
36300 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
36310 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
36320 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
36330 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
36340 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36350 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
36360 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
36370 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
36380 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
36390 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
363a0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
363b0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
363c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
363d0 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
363e0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
363f0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
36400 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
36410 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e  he behavior is n
36420 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a  ot threadsafe..*
36430 2a 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c  * Hence, the sql
36440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
36450 65 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  e() interface.**
36460 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c   is normally onl
36470 79 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20  y useful within 
36480 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
36490 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69  on of .** [appli
364a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
364b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
364c0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
364d0 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a  ], not within.**
364e0 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69   top-level appli
364f0 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a  cation code..**.
36500 2a 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f 75  ** The these rou
36510 74 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70  tines may attemp
36520 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
36530 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
36540 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72   result..** ^For
36550 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
36560 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
36570 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
36580 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
36590 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
365a0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
365b0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
365c0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
365d0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
365e0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
365f0 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
36600 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
36610 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
36620 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
36630 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
36640 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
36650 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
36660 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
36670 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
36680 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
36690 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
366a0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
366b0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
366c0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
366d0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
366e0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
366f0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
36700 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
36710 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
36720 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
36730 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
36740 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
36750 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
36760 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
36770 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
36780 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
36790 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
367a0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
367b0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
367c0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
367d0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
367e0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
367f0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
36800 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
36810 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
36820 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
36830 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
36840 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
36850 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
36860 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
36870 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
36880 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
36890 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
368a0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
368b0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
368c0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
368d0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
368e0 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
368f0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
36900 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
36910 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
36920 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
36930 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
36940 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
36950 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
36960 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
36970 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
36980 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
36990 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
369a0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
369b0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
369c0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
369d0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
369e0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
369f0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
36a00 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
36a10 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
36a20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
36a30 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
36a40 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
36a50 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
36a60 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
36a70 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
36a80 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
36a90 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
36aa0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  te>)^.**.** Note
36ab0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
36ac0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
36ad0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
36ae0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
36af0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
36b00 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
36b10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36b20 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
36b30 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
36b40 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
36b50 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
36b60 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
36b70 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
36b80 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
36b90 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
36ba0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
36bb0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
36bc0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
36bd0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
36be0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
36bf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
36c00 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
36c10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
36c20 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
36c30 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
36c40 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
36c50 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
36c60 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
36c70 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
36c80 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
36c90 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
36ca0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36cb0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
36cc0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
36cd0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
36ce0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
36cf0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
36d00 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
36d10 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
36d20 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
36d30 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
36d40 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
36d50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36d60 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
36d70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36d80 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
36d90 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
36da0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
36db0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
36dc0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
36dd0 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
36de0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
36df0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
36e00 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
36e10 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
36e20 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
36e30 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
36e40 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
36e50 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
36e60 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
36e70 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
36e80 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
36e90 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
36ea0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
36eb0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
36ec0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
36ed0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
36ee0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
36ef0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
36f00 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
36f10 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
36f20 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
36f30 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
36f40 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
36f50 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69   The safest poli
36f60 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
36f70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
36f80 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
36f90 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
36fa0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
36fb0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
36fc0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
36fd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
36fe0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
36ff0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
37000 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
37010 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
37020 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
37030 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
37040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37050 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
37060 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
37070 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
37080 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
37090 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
370a0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
370b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
370c0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
370d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
370e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
370f0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
37100 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
37110 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
37120 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
37130 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
37140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
37150 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
37160 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
37170 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
37180 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
37190 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
371a0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
371b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
371c0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
371d0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
371e0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
371f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37200 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
37210 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
37220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
37230 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
37240 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
37250 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
37260 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
37270 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
37280 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
37290 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
372a0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
372b0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
372c0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
372d0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
372e0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
372f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
37300 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
37310 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
37320 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
37330 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
37340 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
37350 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
37360 6f 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70  o not pass the p
37370 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
37380 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
37390 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
373a0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
373b0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
373c0 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
373d0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
373e0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 69  As long as the i
373f0 6e 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  nput parameters 
37400 61 72 65 20 63 6f 72 72 65 63 74 2c 20 74 68 65  are correct, the
37410 73 65 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  se routines will
37420 20 6f 6e 6c 79 0a 2a 2a 20 66 61 69 6c 20 69 66   only.** fail if
37430 20 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72   an out-of-memor
37440 79 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  y error occurs d
37450 75 72 69 6e 67 20 61 20 66 6f 72 6d 61 74 20 63  uring a format c
37460 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 4f 6e  onversion..** On
37470 6c 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ly the following
37480 20 73 75 62 73 65 74 20 6f 66 20 69 6e 74 65 72   subset of inter
37490 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63  faces are subjec
374a0 74 20 74 6f 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  t to out-of-memo
374b0 72 79 0a 2a 2a 20 65 72 72 6f 72 73 3a 0a 2a 2a  ry.** errors:.**
374c0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
374d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
374e0 62 6c 6f 62 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73  blob().** <li> s
374f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37500 78 74 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  xt().** <li> sql
37510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
37520 31 36 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  16().** <li> sql
37530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37540 73 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  s().** <li> sqli
37550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37560 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  16().** </ul>.**
37570 0a 2a 2a 20 49 66 20 61 6e 20 6f 75 74 2d 6f 66  .** If an out-of
37580 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72 20 6f 63  -memory error oc
37590 63 75 72 73 2c 20 74 68 65 6e 20 74 68 65 20 72  curs, then the r
375a0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
375b0 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e   these.** routin
375c0 65 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  es is the same a
375d0 73 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  s if the column 
375e0 68 61 64 20 63 6f 6e 74 61 69 6e 65 64 20 61 6e  had contained an
375f0 20 53 51 4c 20 4e 55 4c 4c 20 76 61 6c 75 65 2e   SQL NULL value.
37600 0a 2a 2a 20 56 61 6c 69 64 20 53 51 4c 20 4e 55  .** Valid SQL NU
37610 4c 4c 20 72 65 74 75 72 6e 73 20 63 61 6e 20 62  LL returns can b
37620 65 20 64 69 73 74 69 6e 67 75 69 73 68 65 64 20  e distinguished 
37630 66 72 6f 6d 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  from out-of-memo
37640 72 79 20 65 72 72 6f 72 73 0a 2a 2a 20 62 79 20  ry errors.** by 
37650 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 5b 73 71  invoking the [sq
37660 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
37670 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
37680 65 72 20 74 68 65 20 73 75 73 70 65 63 74 0a 2a  er the suspect.*
37690 2a 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  * return value i
376a0 73 20 6f 62 74 61 69 6e 65 64 20 61 6e 64 20 62  s obtained and b
376b0 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 6f 74 68  efore any.** oth
376c0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
376d0 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ace is called on
376e0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
376f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
37700 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
37710 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37720 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
37730 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
37740 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
37750 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
37760 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
37770 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
37780 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
37790 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
377a0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
377b0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
377c0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
377d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
377e0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
377f0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
37800 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
37810 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
37820 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
37830 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
37840 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
37850 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
37860 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
37870 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
37880 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
37890 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
378a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
378b0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
378c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
378d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
378e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
378f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
37900 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
37910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
37920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
37930 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
37940 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
37950 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
37960 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
37970 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
37980 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
37990 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
379a0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
379b0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
379c0 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
379d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
379e0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
379f0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
37a00 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
37a10 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
37a20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
37a30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
37a40 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
37a50 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
37a60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
37a70 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
37a80 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
37a90 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
37aa0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
37ab0 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
37ac0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
37ad0 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
37ae0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
37af0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
37b00 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
37b10 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
37b20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
37b30 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
37b40 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
37b50 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
37b60 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
37b70 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
37b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
37b90 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
37ba0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
37bb0 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
37bc0 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
37bd0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
37be0 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
37bf0 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
37c00 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
37c10 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
37c20 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
37c30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
37c40 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
37c50 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
37c60 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
37c70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
37c80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
37c90 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
37ca0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
37cb0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
37cc0 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
37cd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37ce0 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
37cf0 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
37d00 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
37d10 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
37d20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
37d30 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
37d40 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
37d50 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
37d60 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
37d70 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
37d80 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
37d90 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
37da0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
37db0 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
37dc0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
37dd0 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
37de0 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
37df0 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
37e00 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
37e10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37e20 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
37e30 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
37e40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37e50 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
37e60 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
37e70 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ct.** METHOD: sq
37e80 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
37e90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
37ea0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
37eb0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
37ec0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
37ed0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
37ee0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
37ef0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
37f00 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
37f10 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
37f20 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
37f30 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
37f40 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
37f50 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
37f60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
37f70 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
37f80 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
37f90 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
37fa0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
37fb0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
37fc0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
37fd0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
37fe0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
37ff0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
38000 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
38010 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
38020 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
38030 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
38040 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
38050 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
38060 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
38070 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
38080 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
38090 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
380a0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
380b0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
380c0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
380d0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
380e0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
380f0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
38100 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
38110 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
38120 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
38130 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
38140 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
38150 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
38160 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
38170 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
38180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
38190 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
381a0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
381b0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
381c0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
381d0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
381e0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
381f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
38200 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
38210 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
38220 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
38230 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
38240 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
38250 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
38260 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
38270 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
38280 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
38290 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
382a0 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
382b0 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
382c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
382d0 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
382e0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
382f0 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
38300 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
38310 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
38320 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
38330 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
38340 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
38350 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
38360 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
38370 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
38380 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
38390 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
383a0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
383b0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
383c0 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
383d0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
383e0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
383f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
38400 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
38410 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
38420 67 72 65 67 61 74 65 73 2e 20 54 68 65 20 6f 6e  gregates. The on
38430 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
38440 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 68  etween.** the th
38450 72 65 65 20 22 73 71 6c 69 74 65 33 5f 63 72 65  ree "sqlite3_cre
38460 61 74 65 5f 66 75 6e 63 74 69 6f 6e 2a 22 20 72  ate_function*" r
38470 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
38480 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 0a 2a  text encoding .*
38490 2a 20 65 78 70 65 63 74 65 64 20 66 6f 72 20 74  * expected for t
384a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
384b0 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
384c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
384d0 69 6e 67 20 0a 2a 2a 20 63 72 65 61 74 65 64 29  ing .** created)
384e0 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
384f0 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
38500 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
38510 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
38520 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
38530 61 20 70 6f 69 6e 74 65 72 2e 20 46 75 6e 63 74  a pointer. Funct
38540 69 6f 6e 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ion sqlite3_crea
38550 74 65 5f 77 69 6e 64 6f 77 5f 66 75 6e 63 74 69  te_window_functi
38560 6f 6e 28 29 0a 2a 2a 20 69 73 20 73 69 6d 69 6c  on().** is simil
38570 61 72 2c 20 62 75 74 20 61 6c 6c 6f 77 73 20 74  ar, but allows t
38580 68 65 20 75 73 65 72 20 74 6f 20 73 75 70 70 6c  he user to suppl
38590 79 20 74 68 65 20 65 78 74 72 61 20 63 61 6c 6c  y the extra call
385a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  back functions.*
385b0 2a 20 6e 65 65 64 65 64 20 62 79 20 5b 61 67 67  * needed by [agg
385c0 72 65 67 61 74 65 20 77 69 6e 64 6f 77 20 66 75  regate window fu
385d0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20  nctions]..**.** 
385e0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
385f0 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
38600 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38610 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
38620 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
38630 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
38640 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
38650 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
38660 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
38670 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
38680 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
38690 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
386a0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
386b0 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
386c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
386d0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
386e0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
386f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
38700 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
38710 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
38720 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
38730 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
38740 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
38750 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
3