System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 4dd5eada9bb37464fe3677a7446a9fe767914099:


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 33 2e 32 35 2e 33 22 0a 23 64 65      "3.25.3".#de
1210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1220: 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 32 35 30  ION_NUMBER 30250
1230: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
1240: 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20  E_SOURCE_ID     
1250: 20 22 32 30 31 38 2d 31 31 2d 30 35 20 32 30 3a   "2018-11-05 20:
1260: 33 37 3a 33 38 20 38 39 65 30 39 39 66 62 65 35  37:38 89e099fbe5
1270: 65 31 33 63 33 33 65 36 38 33 62 65 66 30 37 33  e13c33e683bef073
1280: 36 31 32 33 31 63 61 35 32 35 62 38 38 66 37 39  61231ca525b88f79
1290: 30 37 62 65 37 30 39 32 30 35 38 30 30 37 62 37  07be7092058007b7
12a0: 35 30 33 36 66 32 22 0a 0a 2f 2a 0a 2a 2a 20 43  5036f2"../*.** C
12b0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
12c0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
12d0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
12e0: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
12f0: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1300: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1310: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1320: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1330: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1340: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1350: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1360: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1370: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1380: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1390: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
13a0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
13b0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
13c0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
13d0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
13e0: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
13f0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1400: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1410: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1420: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1430: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1440: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1450: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1460: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1470: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1480: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1490: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
14a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14b0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
14c0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
14d0: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
14e0: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
14f0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1500: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1510: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1520: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1530: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1540: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 6e  .** assert( strn
1550: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1560: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1570: 55 52 43 45 5f 49 44 2c 38 30 29 3d 3d 30 20 29  URCE_ID,80)==0 )
1580: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1590: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76  cmp(sqlite3_libv
15a0: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f  ersion(),SQLITE_
15b0: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a  VERSION)==0 );.*
15c0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15d0: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
15e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
15f0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1600: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
1610: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54  e text of [SQLIT
1620: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61  E_VERSION].** ma
1630: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  cro.  ^The sqlit
1640: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
1650: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1660: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1670: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69  e.** to the sqli
1680: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1690: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
16a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
16b0: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63  ersion().** func
16c0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
16d0: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73   for use in DLLs
16e0: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73   since DLL users
16f0: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20   usually do not 
1700: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61  have.** direct a
1710: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20  ccess to string 
1720: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e  constants within
1730: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a   the DLL.  ^The.
1740: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
1750: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66  rsion_number() f
1760: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1770: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c  an integer equal
1780: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56   to.** [SQLITE_V
1790: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
17a0: 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
17b0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
17c0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
17d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
17e0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
17f0: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1800: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1810: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1820: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1830: 6f 72 20 6d 61 63 72 6f 2e 20 20 45 78 63 65 70  or macro.  Excep
1840: 74 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 62  t if SQLite is b
1850: 75 69 6c 74 0a 2a 2a 20 75 73 69 6e 67 20 61 6e  uilt.** using an
1860: 20 65 64 69 74 65 64 20 63 6f 70 79 20 6f 66 20   edited copy of 
1870: 5b 74 68 65 20 61 6d 61 6c 67 61 6d 61 74 69 6f  [the amalgamatio
1880: 6e 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 61 73  n], then the las
1890: 74 20 66 6f 75 72 20 63 68 61 72 61 63 74 65 72  t four character
18a0: 73 0a 2a 2a 20 6f 66 20 74 68 65 20 68 61 73 68  s.** of the hash
18b0: 20 6d 69 67 68 74 20 62 65 20 64 69 66 66 65 72   might be differ
18c0: 65 6e 74 20 66 72 6f 6d 20 5b 53 51 4c 49 54 45  ent from [SQLITE
18d0: 5f 53 4f 55 52 43 45 5f 49 44 5d 2e 29 5e 0a 2a  _SOURCE_ID].)^.*
18e0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
18f0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
1900: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
1910: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1920: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1930: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1940: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1950: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1960: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
1970: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1980: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
1990: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
19a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
19b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
19c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
19d0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
19e0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
19f0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1a00: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
1a10: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
1a20: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
1a30: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
1a40: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
1a50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a60: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
1a70: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
1a80: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
1a90: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
1aa0: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
1ab0: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
1ac0: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
1ad0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
1ae0: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
1af0: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
1b00: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
1b20: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
1b50: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
1b60: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
1b70: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
1b80: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
1b90: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
1ba0: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
1bb0: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
1bc0: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
1bd0: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
1be0: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
1bf0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c00: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
1c10: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1c20: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
1c30: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
1c40: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
1c50: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1c60: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1c70: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
1c80: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
1c90: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
1ca0: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
1cb0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1cc0: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
1cd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ce0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
1cf0: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
1d00: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
1d10: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
1d20: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d30: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
1d40: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
1d50: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
1d60: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
1d70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1d80: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1d90: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
1da0: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
1db0: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
1dc0: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
1dd0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1de0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1df0: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
1e00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1e10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1e20: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1e30: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
1e40: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
1e50: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1e60: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1e70: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1e80: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1e90: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ea0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1eb0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1ec0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1ed0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1ee0: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1ef0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1f00: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1f10: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1f20: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1f30: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1f40: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1f50: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1f60: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1f70: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1f80: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1f90: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1fa0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1fb0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1fc0: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1fd0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1fe0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1ff0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
2000: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
2010: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
2020: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
2030: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
2040: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
2050: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
2060: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
2070: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
2080: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
2090: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
20a0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
20b0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
20c0: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
20d0: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
20e0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
20f0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
2100: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
2110: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
2120: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
2130: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
2140: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
2150: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
2160: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
2170: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
2180: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
2190: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
21a0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
21b0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
21c0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
21d0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
21e0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
21f0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2200: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2210: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2220: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2230: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2240: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2250: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
2260: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
2270: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
2280: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2290: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
22a0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
22b0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
22c0: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
22d0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
22e0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
22f0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2300: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2310: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2320: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2330: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2340: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2350: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2360: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2370: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2380: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2390: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
23a0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
23b0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
23c0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
23d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
23e0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
23f0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2400: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2410: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2420: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2430: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2440: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2450: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2460: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2470: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2480: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2490: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
24a0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
24b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
24c0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
24d0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
24e0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
24f0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2500: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2510: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2520: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2530: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2540: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2550: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2560: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2570: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2580: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2590: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
25a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
25b0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
25c0: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
25d0: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
25e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
25f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2600: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2610: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2620: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2630: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2640: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2650: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2660: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2670: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2680: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2690: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
26a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
26b0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
26c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
26d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
26e0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
26f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2700: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2710: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2720: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2730: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2740: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2750: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
2760: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
2770: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
2780: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
2790: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
27a0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
27b0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27c0: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
27d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
27e0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
27f0: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2800: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2810: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2820: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2830: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2840: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2850: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
2860: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
2870: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
2880: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2890: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
28a0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
28b0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
28c0: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
28d0: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
28e0: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
28f0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2900: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2910: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2920: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2930: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2940: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2950: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2960: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
2970: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
2980: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
2990: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
29a0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
29b0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
29c0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
29d0: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
29e0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
29f0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2a00: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2a10: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2a20: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2a30: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2a40: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2a50: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
2a60: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
2a70: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
2a80: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2a90: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
2aa0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
2ab0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2ac0: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2ad0: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2ae0: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2af0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2b00: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2b30: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2b40: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2b50: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
2b60: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2b70: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
2b80: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2b90: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2ba0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
2bb0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2bc0: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2bd0: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2be0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2bf0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2c00: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c10: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2c30: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2c40: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2c50: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2c60: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2c70: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2c80: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2c90: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ca0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2cb0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2cc0: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2cd0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2ce0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2cf0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2d00: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2d10: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2d20: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2d30: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2d40: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2d50: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2d60: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2d70: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2d80: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2d90: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2da0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2db0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2dc0: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2dd0: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2de0: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2df0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2e00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2e10: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2e20: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2e30: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2e40: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2e50: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2e60: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2e70: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2e80: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2e90: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ea0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2eb0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2ec0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2ed0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2ee0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2ef0: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2f00: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f10: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2f20: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2f30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2f40: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2f50: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2f60: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2f70: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2f80: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2f90: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2fa0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2fb0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2fc0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2fd0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2fe0: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2ff0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
3000: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
3010: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
3020: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
3030: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
3040: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
3050: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
3060: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
3070: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
3080: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
3090: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
30a0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
30b0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
30c0: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
30d0: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
30e0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
30f0: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
3100: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
3110: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
3120: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
3130: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
3140: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
3150: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
3160: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
3170: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
3180: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
3190: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
31a0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
31b0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
31c0: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
31d0: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
31e0: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
31f0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3200: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3210: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3220: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3230: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3240: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3250: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
3260: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3270: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
3280: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
3290: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
32a0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
32b0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
32c0: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
32d0: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
32e0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
32f0: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3300: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3310: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3320: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3330: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3340: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3350: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
3360: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3370: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
3380: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
3390: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
33a0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
33b0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
33c0: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
33d0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
33e0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
33f0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3400: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3410: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3420: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3430: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3440: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3450: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
3460: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
3470: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
3480: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
3490: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
34a0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
34b0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
34c0: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
34d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
34e0: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
34f0: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3500: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3510: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3520: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3530: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3540: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3550: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
3560: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
3570: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
3580: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
3590: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
35a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
35b0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
35c0: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
35d0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
35e0: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
35f0: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
3600: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
3610: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3620: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
3630: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
3640: 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a  e_v2(sqlite3*);.
3650: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
3660: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
3670: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
3680: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
3690: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
36a0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
36b0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
36c0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
36d0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
36e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
36f0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
3700: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
3710: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
3720: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3730: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
3740: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
3750: 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ace.** METHOD: s
3760: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
3770: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3780: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
3790: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
37a0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
37b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
37c0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
37d0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
37e0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
37f0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3800: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3810: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3820: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3830: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3840: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3850: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3860: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3870: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3880: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3890: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
38a0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
38b0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
38c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
38d0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
38e0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
38f0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3900: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3910: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3920: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3930: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3940: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3950: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3960: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3970: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3980: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3990: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
39a0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
39b0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
39c0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
39d0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
39e0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
39f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3a00: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3a10: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3a20: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3a30: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3a40: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3a50: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3a60: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3a70: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3a80: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3a90: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3aa0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3ab0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3ac0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3ad0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3ae0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3af0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3b00: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3b20: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3b30: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3b40: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3b50: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3b60: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3b70: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3b90: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3ba0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3bb0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3bc0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3bd0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3be0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3bf0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3c00: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3c10: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3c20: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3c30: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3c40: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3c50: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3c60: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3c70: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3c80: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3c90: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3ca0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3cb0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69  meter of.** sqli
3cc0: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72  te3_exec() after
3cd0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
3ce0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20  ge string is no 
3cf0: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
3d00: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61  * ^If the 5th pa
3d10: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3d20: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
3d30: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72   NULL and no err
3d40: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68  ors.** occur, th
3d50: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  en sqlite3_exec(
3d60: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74  ) sets the point
3d70: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61  er in its 5th pa
3d80: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55  rameter to.** NU
3d90: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  LL before return
3da0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ing..**.** ^If a
3db0: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3dc0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
3dd0: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
3de0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3df0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
3e00: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77  s SQLITE_ABORT w
3e10: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20  ithout invoking 
3e20: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61  the callback aga
3e30: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75  in and.** withou
3e40: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75  t running any su
3e50: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
3e60: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
3e70: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  The 2nd argument
3e80: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3e90: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3ea0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a  function is the.
3eb0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  ** number of col
3ec0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
3ed0: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72  lt.  ^The 3rd ar
3ee0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3f00: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3f10: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3f20: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61   to strings obta
3f30: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a  ined as if from.
3f40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
3f50: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20  mn_text()], one 
3f60: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  for each column.
3f70: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74    ^If an element
3f80: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20   of a.** result 
3f90: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  row is NULL then
3fa0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
3fb0: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ng string pointe
3fc0: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c  r for the.** sql
3fd0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3fe0: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70  back is a NULL p
3ff0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74  ointer.  ^The 4t
4000: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
4010: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
4020: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
4030: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
4040: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
4050: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e  where each.** en
4060: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74  try represents t
4070: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65  he name of corre
4080: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20  sponding result 
4090: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e  column as obtain
40a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
40b0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
40c0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  )]..**.** ^If th
40d0: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
40e0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
40f0: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
4100: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ter, a pointer.*
4110: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  * to an empty st
4120: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74  ring, or a point
4130: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  er that contains
4140: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
4150: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20   and/or .** SQL 
4160: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
4170: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
4180: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
4190: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  nd the database.
41a0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
41b0: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63  d..**.** Restric
41c0: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tions:.**.** <ul
41d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  >.** <li> The ap
41e0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65  plication must e
41f0: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31  nsure that the 1
4200: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4210: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
4220: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69  *      is a vali
4230: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61  d and open [data
4240: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4250: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
4260: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
4270: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61  ot close the [da
4280: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4290: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  n] specified by.
42a0: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20  **      the 1st 
42b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
42c0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
42d0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
42e0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
42f0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
4300: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f  tion must not mo
4310: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61  dify the SQL sta
4320: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73  tement text pass
4330: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20  ed into.**      
4340: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
4350: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  r of sqlite3_exe
4360: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
4370: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
4380: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ing..** </ul>.*/
4390: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
43a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
43b0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
43e0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
43f0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
4400: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
4410: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4420: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
4430: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  uated */.  int (
4440: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
4450: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
4460: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
4470: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
4480: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
4490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
44b0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
44c0: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
44d0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
44e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44f0: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
4500: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
4510: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
4520: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
4530: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4540: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64  : {result code d
4550: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4560: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
4570: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4580: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4590: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
45a0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
45b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
45c0: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
45d0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
45e0: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
45f0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4600: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4610: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4620: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65   See also: [exte
4630: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4640: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f   definitions].*/
4650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4660: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
4670: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
4680: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
4690: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
46a0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
46b0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
46c0: 20 20 20 20 31 20 20 20 2f 2a 20 47 65 6e 65 72      1   /* Gener
46d0: 69 63 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ic error */.#def
46e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
46f0: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
4700: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
4710: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
4720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4730: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
4740: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
4750: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
4760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4770: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
4780: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
4790: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
47a0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
47c0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
47d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
47e0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
47f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
4800: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
4810: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
4820: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
4830: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4840: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
4850: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
4860: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
4880: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
4890: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
48a0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
48b0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
48c0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
48d0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
48e0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
48f0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
4900: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
4910: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
4920: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
4930: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4940: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4960: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
4970: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4980: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
4990: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
49a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49b0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
49c0: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
49d0: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
49e0: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
49f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
4a00: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
4a10: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
4a20: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
4a30: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4a50: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
4a60: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
4a70: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
4a80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a90: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
4aa0: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
4ab0: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
4ac0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4ad0: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
4ae0: 20 20 31 36 20 20 20 2f 2a 20 49 6e 74 65 72 6e    16   /* Intern
4af0: 61 6c 20 75 73 65 20 6f 6e 6c 79 20 2a 2f 0a 23  al use only */.#
4b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
4b10: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
4b20: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
4b30: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
4b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b50: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
4b60: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
4b70: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
4b80: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
4b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
4ba0: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
4bb0: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
4bc0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4be0: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
4bf0: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
4c00: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
4c10: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
4c20: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
4c30: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
4c40: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
4c50: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
4c60: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
4c70: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
4c80: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
4c90: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
4ca0: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
4cb0: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
4cc0: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
4cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ce0: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
4cf0: 20 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a   /* Not used */.
4d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d10: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4d20: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4d30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4d40: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d60: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4d70: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4d80: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4d90: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4db0: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
4dc0: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
4dd0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4de0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4df0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
4e00: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
4e10: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4e20: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4e30: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4e40: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4e50: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4e60: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4e70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4e80: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4e90: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4ea0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4eb0: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4ec0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4ed0: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4ee0: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4ef0: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
4f00: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4f10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4f20: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4f30: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4f40: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4f50: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4f60: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4f70: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
4f80: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
4f90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4fa0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4fb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4fc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4fd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4fe0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4ff0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
5000: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
5010: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
5020: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
5030: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
5040: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
5050: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
5060: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
5070: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
5080: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61  ersion 3.3.8 [da
5090: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61  teof:3.3.8].** a
50a0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
50b0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
50c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
50d0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
50e0: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
50f0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
5100: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
5110: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
5120: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
5130: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
5140: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
5150: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
5160: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
5170: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
5180: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
5190: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
51a0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
51b0: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
51c0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
51d0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
51e0: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
51f0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
5200: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
5220: 52 4f 52 5f 4d 49 53 53 49 4e 47 5f 43 4f 4c 4c  ROR_MISSING_COLL
5230: 53 45 51 20 20 20 28 53 51 4c 49 54 45 5f 45 52  SEQ   (SQLITE_ER
5240: 52 4f 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ROR | (1<<8)).#d
5250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
5260: 4f 52 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  OR_RETRY        
5270: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 45 52 52       (SQLITE_ERR
5280: 4f 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  OR | (2<<8)).#de
5290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
52a0: 52 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  R_SNAPSHOT      
52b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 45 52 52 4f      (SQLITE_ERRO
52c0: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5310: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5320: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
5330: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5340: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
5360: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
5370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5380: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5390: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
53a0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
53b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53c0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
53e0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5400: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
5420: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
5440: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
5460: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
5480: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5490: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
54a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
54b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
54c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
54d0: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
54e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5500: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5510: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5520: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5530: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
5540: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5550: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
5560: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5570: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
5580: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5590: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
55a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
55c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55d0: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
55e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55f0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5600: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5610: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5620: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
5630: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
5640: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5650: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
5660: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5670: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
5680: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5690: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
56a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
56b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
56c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
56d0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
56e0: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
56f0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5700: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5710: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5720: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5730: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
5740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5750: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
5760: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5770: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
5780: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5790: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
57a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57b0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
57c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57d0: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
57e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57f0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5800: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5810: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5820: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5830: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5850: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
5860: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
5870: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
5880: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5890: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
58a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
58b0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
58c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58d0: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
58e0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58f0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5900: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5910: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5920: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5930: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
5940: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5950: 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20  E_IOERR_VNODE   
5960: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5970: 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38  E_IOERR | (27<<8
5980: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5990: 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20  E_IOERR_AUTH    
59a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
59b0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38  E_IOERR | (28<<8
59c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
59d0: 45 5f 49 4f 45 52 52 5f 42 45 47 49 4e 5f 41 54  E_IOERR_BEGIN_AT
59e0: 4f 4d 49 43 20 20 20 20 20 20 28 53 51 4c 49 54  OMIC      (SQLIT
59f0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 39 3c 3c 38  E_IOERR | (29<<8
5a00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a10: 45 5f 49 4f 45 52 52 5f 43 4f 4d 4d 49 54 5f 41  E_IOERR_COMMIT_A
5a20: 54 4f 4d 49 43 20 20 20 20 20 28 53 51 4c 49 54  TOMIC     (SQLIT
5a30: 45 5f 49 4f 45 52 52 20 7c 20 28 33 30 3c 3c 38  E_IOERR | (30<<8
5a40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a50: 45 5f 49 4f 45 52 52 5f 52 4f 4c 4c 42 41 43 4b  E_IOERR_ROLLBACK
5a60: 5f 41 54 4f 4d 49 43 20 20 20 28 53 51 4c 49 54  _ATOMIC   (SQLIT
5a70: 45 5f 49 4f 45 52 52 20 7c 20 28 33 31 3c 3c 38  E_IOERR | (31<<8
5a80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a90: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
5aa0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
5ab0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
5ac0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ad0: 54 45 5f 4c 4f 43 4b 45 44 5f 56 54 41 42 20 20  TE_LOCKED_VTAB  
5ae0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5af0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 32 3c  TE_LOCKED |  (2<
5b00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b10: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5b20: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5b30: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5b40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b50: 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48  LITE_BUSY_SNAPSH
5b60: 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51  OT           (SQ
5b70: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5b80: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b90: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
5ba0: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
5bb0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5bc0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5bd0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5be0: 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20  _ISDIR          
5bf0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5c00: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5c20: 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20  EN_FULLPATH     
5c30: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5c40: 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  EN | (3<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5c60: 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20  OPEN_CONVPATH   
5c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5c80: 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OPEN | (4<<8)).#
5c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5ca0: 4e 54 4f 50 45 4e 5f 44 49 52 54 59 57 41 4c 20  NTOPEN_DIRTYWAL 
5cb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5cc0: 4e 54 4f 50 45 4e 20 7c 20 28 35 3c 3c 38 29 29  NTOPEN | (5<<8))
5cd0: 20 2f 2a 20 4e 6f 74 20 55 73 65 64 20 2a 2f 0a   /* Not Used */.
5ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5cf0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5d00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5d10: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 43 4f 52 52 55 50 54 5f 53 45 51 55 45 4e 43 45  CORRUPT_SEQUENCE
5d40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5d50: 43 4f 52 52 55 50 54 20 7c 20 28 32 3c 3c 38 29  CORRUPT | (2<<8)
5d60: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d70: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5d80: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5d90: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5da0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5db0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5dc0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5dd0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5de0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5df0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5e00: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
5e10: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5e20: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5e30: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5e40: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
5e50: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5e60: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5e70: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5e80: 59 5f 43 41 4e 54 49 4e 49 54 20 20 20 20 20 20  Y_CANTINIT      
5e90: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5ea0: 59 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  Y | (5<<8)).#def
5eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5ec0: 4e 4c 59 5f 44 49 52 45 43 54 4f 52 59 20 20 20  NLY_DIRECTORY   
5ed0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ee0: 4e 4c 59 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  NLY | (6<<8)).#d
5ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
5f00: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
5f10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
5f20: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
5f30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f40: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
5f50: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5f60: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
5f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f80: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
5f90: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
5fa0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
5fb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5fd0: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
5fe0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ff0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
6000: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6010: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
6020: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6030: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
6040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6050: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
6060: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6070: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
6080: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6090: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
60a0: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
60b0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
60c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
60d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
60e0: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
60f0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6100: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
6110: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6120: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
6130: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6140: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
6150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6160: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
6170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6180: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
6190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61a0: 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44  CONSTRAINT_ROWID
61b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
61c0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c  CONSTRAINT |(10<
61d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
61e0: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56  ITE_NOTICE_RECOV
61f0: 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c  ER_WAL      (SQL
6200: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c  ITE_NOTICE | (1<
6210: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6220: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56  ITE_NOTICE_RECOV
6230: 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c  ER_ROLLBACK (SQL
6240: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c  ITE_NOTICE | (2<
6250: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6260: 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f  ITE_WARNING_AUTO
6270: 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c  INDEX       (SQL
6280: 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31  ITE_WARNING | (1
6290: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
62a0: 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20  LITE_AUTH_USER  
62b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
62c0: 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c  LITE_AUTH | (1<<
62d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
62e0: 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41  TE_OK_LOAD_PERMA
62f0: 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51 4c 49  NENTLY     (SQLI
6300: 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29 29 0a  TE_OK | (1<<8)).
6310: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6320: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20   Flags For File 
6330: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a  Open Operations.
6340: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
6350: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
6360: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
6370: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  he.** 3rd parame
6380: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
6390: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
63a0: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
63b0: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
63c0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
63d0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
63e0: 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69  method..*/.#defi
63f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
6400: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
6410: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
6420: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6430: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6440: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
6450: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
6460: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
6470: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6480: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6490: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
64a0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
64b0: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
64c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
64d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
64e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
64f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
6500: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
6510: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6520: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
6530: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
6540: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
6550: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6560: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
6570: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
6580: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
6590: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
65a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  ne SQLITE_OPEN_U
65b0: 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RI              
65c0: 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f  0x00000040  /* O
65d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
65e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
65f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6600: 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20  EMORY           
6610: 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f  0x00000080  /* O
6620: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6630: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6640: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6650: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
6660: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
6670: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6680: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
6690: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
66a0: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
66b0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
66c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
66d0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
66e0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
66f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6700: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6710: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
6720: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
6730: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6740: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
6750: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
6760: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
6770: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6780: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
6790: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
67a0: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
67b0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
67c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
67d0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
67e0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
67f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6800: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
6810: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
6820: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
6830: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6840: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
6860: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
6870: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
6880: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6890: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
68a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
68b0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
68c0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
68d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
68e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
6900: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
6910: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
6920: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6930: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6940: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57  ne SQLITE_OPEN_W
6950: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AL              
6960: 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56  0x00080000  /* V
6970: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52  FS only */../* R
6980: 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20  eserved:        
6990: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
69a0: 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a   0x00F00000 */..
69b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
69c0: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
69d0: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
69e0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
69f0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f  ristics method o
6a00: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
6a10: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
6a20: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
6a30: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
6a40: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
6a50: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
6a60: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
6a70: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
6a80: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
6a90: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
6aa0: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
6ab0: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
6ac0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6ad0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
6ae0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
6af0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
6b00: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
6b10: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
6b20: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
6b30: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6b40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
6b50: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
6b60: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
6b70: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
6b80: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
6b90: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
6ba0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
6bb0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
6bc0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
6bd0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
6be0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6bf0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6c00: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
6c10: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
6c20: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
6c30: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
6c40: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
6c50: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
6c60: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
6c70: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
6c80: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
6c90: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
6ca0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6cb0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
6cc0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6cd0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
6ce0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
6cf0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
6d00: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
6d10: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20   xWrite().  The 
6d20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6d30: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6d40: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6d50: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65  that.** after re
6d60: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  boot following a
6d70: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20   crash or power 
6d80: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62  loss, the only b
6d90: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c  ytes in a.** fil
6da0: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74  e that were writ
6db0: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69  ten at the appli
6dc0: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67  cation level mig
6dd0: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a  ht have changed.
6de0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61  ** and that adja
6df0: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e  cent bytes, even
6e00: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68   bytes within th
6e10: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72  e same sector ar
6e20: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20  e.** guaranteed 
6e30: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e  to be unchanged.
6e40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6e50: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
6e60: 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67  HEN_OPEN.** flag
6e70: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6e80: 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  a file cannot be
6e90: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70   deleted when op
6ea0: 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49  en.  The.** SQLI
6eb0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
6ec0: 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  LE flag indicate
6ed0: 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20  s that the file 
6ee0: 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e  is on.** read-on
6ef0: 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e  ly media and can
6f00: 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65  not be changed e
6f10: 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73  ven by processes
6f20: 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65   with.** elevate
6f30: 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2a  d privileges..**
6f40: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
6f50: 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49  OCAP_BATCH_ATOMI
6f60: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
6f70: 20 74 68 61 74 20 74 68 65 20 75 6e 64 65 72 6c   that the underl
6f80: 79 69 6e 67 0a 2a 2a 20 66 69 6c 65 73 79 73 74  ying.** filesyst
6f90: 65 6d 20 73 75 70 70 6f 72 74 73 20 64 6f 69 6e  em supports doin
6fa0: 67 20 6d 75 6c 74 69 70 6c 65 20 77 72 69 74 65  g multiple write
6fb0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 74 6f 6d   operations atom
6fc0: 69 63 61 6c 6c 79 20 77 68 65 6e 20 74 68 6f 73  ically when thos
6fd0: 65 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61  e.** write opera
6fe0: 74 69 6f 6e 73 20 61 72 65 20 62 72 61 63 6b 65  tions are bracke
6ff0: 74 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 46  ted by [SQLITE_F
7000: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
7010: 43 5f 57 52 49 54 45 5d 20 61 6e 64 0a 2a 2a 20  C_WRITE] and.** 
7020: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
7030: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
7040: 45 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  E]..*/.#define S
7050: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7060: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
7070: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
7080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7090: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
70a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
70b0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
70c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70d0: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
70e0: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
70f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7100: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
7110: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7120: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
7130: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
7140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7150: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
7160: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7170: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
7180: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
71b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
71c0: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
71d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
71e0: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
71f0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
7200: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7210: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
7220: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7230: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
7240: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
7250: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
7260: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
7270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7280: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
7290: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
72a0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
72b0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
72c0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
72d0: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
72e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
72f0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
7300: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30  ITE    0x0000100
7310: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7320: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
7330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7340: 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65  00002000.#define
7350: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
7360: 54 43 48 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  TCH_ATOMIC      
7370: 20 20 20 20 20 30 78 30 30 30 30 34 30 30 30 0a       0x00004000.
7380: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7390: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
73a0: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
73b0: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
73c0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
73d0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
73e0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
73f0: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
7400: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
7410: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
7420: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
7430: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7440: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
7450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7460: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
7470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7480: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
7490: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
74a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
74b0: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
74c0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
74d0: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
74e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
74f0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
7500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7510: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
7520: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
7530: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
7540: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
7550: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
7560: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7570: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
7580: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
7590: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
75a0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
75b0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
75c0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
75d0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
75e0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
75f0: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
7600: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
7610: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
7620: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
7630: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
7640: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
7650: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
7660: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
7670: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
7680: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
7690: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
76a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
76b0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
76c0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
76d0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
76e0: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
76f0: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
7700: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
7710: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
7720: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
7730: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
7740: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
7750: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
7760: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
7770: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7780: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7790: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
77a0: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
77b0: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
77c0: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
77d0: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
77e0: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
77f0: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
7800: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
7810: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
7820: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
7830: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
7840: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
7850: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
7860: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
7870: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7880: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7890: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
78a0: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
78b0: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
78c0: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
78d0: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
78e0: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
78f0: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
7900: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
7910: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
7920: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
7930: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
7940: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7950: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
7960: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
7970: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
7980: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7990: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
79a0: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
79b0: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
79c0: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
79d0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
79e0: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
79f0: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
7a00: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
7a10: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
7a20: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7a30: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
7a40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7a50: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
7a60: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
7a70: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7a80: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
7a90: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
7aa0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7ab0: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
7ac0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
7ad0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7ae0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
7af0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
7b00: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
7b10: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
7b20: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7b30: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7b40: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
7b50: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
7b60: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7b70: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
7b80: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
7b90: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
7ba0: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
7bb0: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
7bc0: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
7bd0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
7be0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7bf0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
7c00: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
7c10: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
7c20: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7c30: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7c40: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7c50: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
7c60: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7c70: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7c80: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
7c90: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7ca0: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
7cb0: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
7cc0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
7cd0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7ce0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7cf0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
7d00: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
7d10: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
7d20: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7d30: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7d40: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
7d50: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
7d60: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
7d70: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
7d80: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
7d90: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7da0: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
7db0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7dc0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
7dd0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
7de0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7df0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
7e00: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
7e10: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
7e20: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7e30: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7e40: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
7e50: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7e60: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7e70: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7e80: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
7e90: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7ea0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7eb0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
7ec0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
7ed0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
7ee0: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
7ef0: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
7f00: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
7f10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7f20: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7f30: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7f40: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
7f50: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
7f60: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7f70: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
7f80: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
7f90: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
7fa0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7fb0: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7fc0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7fd0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7fe0: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
7ff0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
8000: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
8010: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
8020: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
8030: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
8040: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
8050: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
8060: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
8070: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
8080: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
8090: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
80a0: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
80b0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
80c0: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
80d0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
80e0: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
80f0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
8100: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
8110: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
8120: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
8130: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
8140: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
8150: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
8160: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
8170: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8180: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
8190: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
81a0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
81b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
81c0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
81d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
81e0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
81f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8200: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
8210: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
8220: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
8230: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
8240: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
8250: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
8260: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
8270: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
8280: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
8290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
82a0: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
82b0: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
82c0: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
82d0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
82e0: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
82f0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
8300: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
8310: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
8320: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
8330: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
8340: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
8350: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
8360: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
8370: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
8380: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
8390: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
83a0: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
83b0: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
83c0: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
83d0: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
83e0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
83f0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
8400: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
8410: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
8420: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
8430: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
8440: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
8450: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
8460: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
8470: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
8480: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
8490: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
84a0: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
84b0: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
84c0: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
84d0: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
84e0: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
84f0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
8500: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
8510: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
8520: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
8530: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
8540: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
8550: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
8560: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
8570: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
8580: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
8590: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
85a0: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
85b0: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
85c0: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
85d0: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
85e0: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
85f0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
8600: 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20  use..** A [file 
8610: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
8620: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
8630: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
8640: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
8650: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
8660: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
8670: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
8680: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
8690: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
86a0: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
86b0: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
86c0: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  s.  VFS implemen
86d0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a  tations should.*
86e0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
86f0: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66  _NOTFOUND] for f
8700: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8710: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f  des that they do
8720: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a   not.** recogniz
8730: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
8740: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
8750: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
8760: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
8770: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
8780: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
8790: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
87a0: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
87b0: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
87c0: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
87d0: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
87e0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
87f0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
8800: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
8810: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
8820: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
8830: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
8840: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
8850: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
8860: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
8870: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
8880: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8890: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
88a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
88b0: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
88c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
88d0: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
88e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
88f0: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
8900: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8910: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
8920: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8930: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
8940: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8950: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
8960: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8970: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
8980: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8990: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
89a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
89b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
89c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
89d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
89e0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  L].** <li> [SQLI
89f0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
8a00: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a  ABLE_WHEN_OPEN].
8a10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8a20: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
8a30: 4f 56 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c  OVERWRITE].** <l
8a40: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8a50: 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c  _IMMUTABLE].** <
8a60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8a70: 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 5d 0a  P_BATCH_ATOMIC].
8a80: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
8a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8aa0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
8ab0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
8ac0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
8ad0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
8ae0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8af0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
8b00: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
8b10: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
8b20: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
8b30: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8b40: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8b50: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8b60: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8b70: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8b80: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
8b90: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8ba0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
8bb0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
8bc0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
8bd0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
8be0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
8bf0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
8c00: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
8c10: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
8c20: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
8c30: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8c40: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8c50: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8c60: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8c70: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8c80: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8c90: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
8ca0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
8cb0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
8cc0: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8cd0: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
8ce0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
8cf0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
8d00: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
8d10: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
8d20: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
8d30: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8d40: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8d50: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8d60: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8d70: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8d80: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8d90: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
8da0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
8db0: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
8dc0: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8dd0: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
8de0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8df0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8e00: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
8e10: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
8e20: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8e30: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8e40: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8e50: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8e60: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8e70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8e80: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8e90: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8ea0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8eb0: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
8ec0: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8ed0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8ee0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8ef0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
8f00: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
8f10: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8f20: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
8f30: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8f40: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8f50: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8f60: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8f70: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8f80: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8f90: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8fa0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8fb0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8fc0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8fd0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8fe0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
8ff0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
9000: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
9010: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
9020: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
9030: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
9040: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
9050: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
9060: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
9070: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
9080: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
9090: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
90a0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
90b0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
90c0: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
90d0: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
90e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
90f0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
9100: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
9110: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
9120: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
9130: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
9140: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
9150: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
9160: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
9170: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
9180: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
9190: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
91a0: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
91b0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
91c0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
91d0: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
91e0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
91f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
9200: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
9210: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
9220: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
9230: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
9240: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
9250: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
9260: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
9270: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9280: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9290: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
92a0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
92b0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
92c0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
92d0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
92e0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
92f0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
9300: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
9310: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
9320: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
9330: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
9340: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
9350: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
9360: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
9370: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
9380: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
9390: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
93a0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
93b0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
93c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
93d0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
93e0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
93f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
9400: 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65  CKSTATE]].** The
9410: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
9420: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
9430: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
9440: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
9450: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
9460: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
9470: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
9480: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
9490: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
94a0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
94b0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
94c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
94d0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
94e0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
94f0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
9500: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
9510: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
9520: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
9530: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
9540: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
9550: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
9560: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
9570: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
9580: 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  and is only avai
9590: 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53  lable when the S
95a0: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f  QLITE_TEST.** co
95b0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
95c0: 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
95d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
95e0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
95f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9600: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
9610: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
9620: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
9630: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
9640: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
9650: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
9660: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
9670: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
9680: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
9690: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
96a0: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
96b0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
96c0: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
96d0: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
96e0: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
96f0: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
9700: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
9710: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
9720: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
9730: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
9740: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
9750: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
9760: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
9770: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
9780: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9790: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
97a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
97b0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
97c0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
97d0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
97e0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
97f0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
9800: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9810: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
9820: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
9830: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
9840: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
9850: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
9860: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
9870: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
9880: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
9890: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
98a0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
98b0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
98c0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
98d0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
98e0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
98f0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
9900: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
9910: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
9920: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
9930: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
9940: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
9950: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
9960: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
9970: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
9980: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9990: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
99a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
99b0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
99c0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
99d0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
99e0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
99f0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9a00: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9a10: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
9a20: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9a30: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9a40: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9a50: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e  OURNAL_POINTER].
9a60: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9a70: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9a80: 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  L_POINTER]].** T
9a90: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9aa0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9ab0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9ac0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
9ad0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
9ae0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9af0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
9b00: 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c  with the journal
9b10: 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a   file (either.**
9b20: 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a   the [rollback j
9b30: 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b  ournal] or the [
9b40: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d  write-ahead log]
9b50: 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ) for a particul
9b60: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9b70: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9b80: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9b90: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9ba0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9bb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9bc0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9bd0: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9be0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9bf0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9c00: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9c10: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9c20: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9c30: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9c40: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9c50: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9c60: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
9c70: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
9c80: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
9c90: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
9ca0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
9cb0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9cc0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9cd0: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9ce0: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9cf0: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9d00: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9d10: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9d20: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
9d30: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9d40: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9d50: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9d60: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
9d70: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
9d80: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
9d90: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
9da0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
9db0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
9dc0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9dd0: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9de0: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
9df0: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
9e00: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
9e10: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
9e20: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
9e30: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
9e40: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
9e50: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
9e60: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
9e70: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
9e80: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9e90: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
9ea0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9eb0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9ec0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
9ed0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
9ee0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9ef0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9f00: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9f10: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
9f20: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
9f30: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9f40: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9f50: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9f60: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9f70: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9f80: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
9f90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9fa0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
9fb0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9fc0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9fd0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
9fe0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
9ff0: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
a000: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
a010: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
a020: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
a030: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
a040: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
a050: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
a060: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
a070: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
a080: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
a090: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
a0a0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
a0b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a0c0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
a0d0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
a0e0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
a0f0: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
a100: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
a110: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
a120: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
a130: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
a140: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a150: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
a160: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a170: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
a180: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
a190: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
a1a0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
a1b0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
a1c0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
a1d0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
a1e0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
a1f0: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
a200: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
a210: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
a220: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
a230: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
a240: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
a250: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
a260: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
a270: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
a280: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
a290: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
a2a0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
a2b0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
a2c0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
a2d0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
a2e0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
a2f0: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
a300: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
a310: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
a320: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
a330: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
a340: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
a350: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
a360: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
a370: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
a380: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
a390: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
a3a0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
a3b0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
a3c0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
a3d0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
a3e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
a3f0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
a400: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
a410: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
a420: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
a430: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
a440: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
a450: 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  st integer is th
a460: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
a470: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
a480: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
a490: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
a4a0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
a4b0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
a4c0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
a4d0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
a4e0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
a4f0: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
a500: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
a510: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
a520: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
a530: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
a540: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
a550: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
a560: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
a570: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
a580: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
a590: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a5a0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
a5b0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a5c0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a5d0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
a5e0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a5f0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a600: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
a610: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
a620: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
a630: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
a640: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
a650: 20 6c 6f 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d   log ([WAL file]
a660: 29 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  ) and shared mem
a670: 6f 72 79 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65  ory.** files use
a680: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
a690: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
a6a0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
a6b0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
a6c0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
a6d0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a6e0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a6f0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a700: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a710: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a720: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a730: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a740: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a750: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a760: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a770: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a780: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a790: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a7a0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a7b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a7c0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a7d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a7e0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
a7f0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a800: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
a810: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
a820: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
a830: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
a840: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a850: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a860: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a870: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a880: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a890: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a8a0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a8b0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a8c0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
a8d0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
a8e0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
a8f0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
a900: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a910: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a920: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a930: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a940: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
a950: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
a960: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a970: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a980: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a990: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a9a0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a9b0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a9c0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a9d0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a9e0: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
a9f0: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
aa00: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
aa10: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
aa20: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
aa30: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
aa40: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
aa50: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
aa60: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
aa70: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
aa80: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
aa90: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
aaa0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
aab0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
aac0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
aad0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
aae0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
aaf0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
ab00: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
ab10: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
ab20: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
ab30: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
ab40: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
ab50: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
ab60: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
ab70: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
ab80: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
ab90: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
aba0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
abb0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
abc0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
abd0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
abe0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
abf0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
ac00: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
ac10: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
ac20: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
ac30: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
ac40: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
ac50: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
ac60: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
ac70: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
ac80: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
ac90: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
aca0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
acb0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
acc0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
acd0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
ace0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
acf0: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
ad00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
ad10: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
ad20: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
ad30: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
ad40: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
ad50: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
ad60: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
ad70: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
ad80: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
ad90: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
ada0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
adb0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
adc0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
add0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
ade0: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
adf0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
ae00: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
ae10: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
ae20: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
ae30: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
ae40: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
ae50: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
ae60: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
ae70: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
ae80: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
ae90: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
aea0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
aeb0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
aec0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
aed0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
aee0: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
aef0: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
af00: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
af10: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
af20: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
af30: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
af40: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
af50: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
af60: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
af70: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
af80: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
af90: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
afa0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
afb0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
afc0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
afe0: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
aff0: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
b000: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
b010: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
b020: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
b030: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
b040: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
b050: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
b060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
b070: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
b080: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
b090: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
b0a0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
b0b0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
b0c0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
b0d0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
b0e0: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
b0f0: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
b100: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
b110: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
b120: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
b130: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
b140: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
b150: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b160: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
b170: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
b180: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
b190: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
b1a0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b1b0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
b1c0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
b1d0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
b1e0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
b1f0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
b200: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b210: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
b220: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
b230: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
b240: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
b250: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b260: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b270: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
b280: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
b290: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
b2a0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
b2b0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
b2c0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
b2d0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
b2e0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
b2f0: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
b300: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
b310: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
b320: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
b330: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
b340: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
b350: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
b360: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b370: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b380: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
b390: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
b3a0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
b3b0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
b3c0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
b3d0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
b3e0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
b3f0: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
b400: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
b410: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
b420: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
b430: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
b440: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
b450: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
b460: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
b470: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
b480: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b490: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
b4a0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
b4b0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
b4c0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
b4d0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
b4e0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
b4f0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b500: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
b510: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
b520: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
b530: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
b540: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
b550: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
b560: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
b570: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
b580: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
b590: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
b5a0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
b5b0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
b5c0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
b5d0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
b5e0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
b5f0: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
b600: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
b610: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b620: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b630: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
b640: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
b650: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b660: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
b670: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
b680: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
b690: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
b6a0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
b6b0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
b6c0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
b6d0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b6e0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b6f0: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b700: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b710: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b720: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b730: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b740: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b750: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b760: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b770: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b780: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b790: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b7a0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b7b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b7c0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b7d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b7e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
b7f0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
b800: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
b810: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
b820: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
b830: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
b840: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
b850: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
b860: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
b870: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
b880: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
b890: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
b8a0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
b8b0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
b8c0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
b8d0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
b8e0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
b8f0: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
b900: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
b910: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
b920: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
b930: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
b940: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
b950: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
b960: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
b970: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
b980: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
b990: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
b9a0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
b9b0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
b9c0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
b9d0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
b9e0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
b9f0: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
ba00: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
ba10: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
ba20: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
ba30: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
ba40: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
ba50: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
ba60: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ba70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
ba80: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
ba90: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
baa0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
bab0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
bac0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
bad0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
bae0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
baf0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
bb00: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
bb10: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
bb20: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
bb30: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
bb40: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
bb50: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
bb60: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
bb70: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
bb80: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
bb90: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
bba0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
bbb0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
bbc0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
bbd0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
bbe0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
bbf0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
bc00: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
bc10: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
bc20: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
bc30: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
bc40: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
bc50: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
bc60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
bc70: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
bc80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
bc90: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
bca0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
bcb0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
bcc0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
bcd0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
bce0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
bcf0: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
bd00: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
bd10: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
bd20: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
bd30: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
bd40: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
bd50: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
bd60: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
bd70: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
bd80: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
bd90: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
bda0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
bdb0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
bdc0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
bdd0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
bde0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
bdf0: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
be00: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
be10: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
be20: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
be30: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
be40: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
be50: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
be60: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
be70: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
be80: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
be90: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
bea0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
beb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bec0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
bed0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bee0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
bef0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
bf00: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
bf10: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
bf20: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
bf30: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
bf40: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
bf50: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
bf60: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
bf70: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
bf80: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
bf90: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
bfa0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
bfb0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
bfc0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
bfd0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
bfe0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
bff0: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
c000: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
c010: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
c020: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
c030: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
c040: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
c050: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
c060: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
c070: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c080: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
c090: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c0a0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
c0b0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
c0c0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
c0d0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
c0e0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
c0f0: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
c100: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
c110: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
c120: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
c130: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
c140: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
c150: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
c160: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
c170: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
c180: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
c190: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c1a0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
c1b0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c1c0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c1d0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
c1e0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
c1f0: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
c200: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
c210: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
c220: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
c230: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
c240: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
c250: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
c260: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
c270: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
c280: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
c290: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
c2a0: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
c2b0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
c2c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c2d0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
c2e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c2f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c300: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
c310: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
c320: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
c330: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
c340: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
c350: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
c360: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
c370: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
c380: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
c390: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
c3a0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
c3b0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
c3c0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
c3d0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
c3e0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
c3f0: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
c400: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
c410: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
c420: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
c430: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
c440: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
c450: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
c460: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
c470: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
c480: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
c490: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
c4a0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
c4b0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
c4c0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
c4d0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
c4e0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
c4f0: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
c500: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
c510: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
c520: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
c530: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
c540: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
c550: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
c560: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
c570: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
c580: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
c590: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
c5a0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
c5b0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c5c0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
c5d0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
c5e0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
c5f0: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
c600: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c610: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
c620: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
c630: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c640: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
c650: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c660: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
c670: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
c680: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
c690: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
c6a0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
c6b0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
c6c0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
c6d0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
c6e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
c6f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c700: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c710: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
c720: 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   If the [SQLITE_
c730: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c740: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
c750: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
c760: 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  OK, then.** the 
c770: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
c780: 69 73 20 70 6c 61 63 65 64 20 69 6e 20 22 62 61  is placed in "ba
c790: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 22 2c  tch write mode",
c7a0: 20 77 68 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20   which.** means 
c7b0: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77  all subsequent w
c7c0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
c7d0: 77 69 6c 6c 20 62 65 20 64 65 66 65 72 72 65 64  will be deferred
c7e0: 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f   and done.** ato
c7f0: 6d 69 63 61 6c 6c 79 20 61 74 20 74 68 65 20 6e  mically at the n
c800: 65 78 74 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ext [SQLITE_FCNT
c810: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
c820: 57 52 49 54 45 5d 2e 20 20 53 79 73 74 65 6d 73  WRITE].  Systems
c830: 0a 2a 2a 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  .** that do not 
c840: 73 75 70 70 6f 72 74 20 62 61 74 63 68 20 61 74  support batch at
c850: 6f 6d 69 63 20 77 72 69 74 65 73 20 77 69 6c 6c  omic writes will
c860: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
c870: 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c  OTFOUND..** ^Fol
c880: 6c 6f 77 69 6e 67 20 61 20 73 75 63 63 65 73 73  lowing a success
c890: 66 75 6c 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ful SQLITE_FCNTL
c8a0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c8b0: 49 54 45 20 61 6e 64 20 70 72 69 6f 72 20 74 6f  ITE and prior to
c8c0: 0a 2a 2a 20 74 68 65 20 63 6c 6f 73 69 6e 67 20  .** the closing 
c8d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c8e0: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c8f0: 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  E] or.** [SQLITE
c900: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
c910: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53  ATOMIC_WRITE], S
c920: 51 4c 69 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a  QLite will make.
c930: 2a 2a 20 6e 6f 20 56 46 53 20 69 6e 74 65 72 66  ** no VFS interf
c940: 61 63 65 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65  ace calls on the
c950: 20 73 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66   same [sqlite3_f
c960: 69 6c 65 5d 20 66 69 6c 65 20 64 65 73 63 72 69  ile] file descri
c970: 70 74 6f 72 0a 2a 2a 20 65 78 63 65 70 74 20 66  ptor.** except f
c980: 6f 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  or calls to the 
c990: 78 57 72 69 74 65 20 6d 65 74 68 6f 64 20 61 6e  xWrite method an
c9a0: 64 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  d the xFileContr
c9b0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74  ol method.** wit
c9c0: 68 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  h [SQLITE_FCNTL_
c9d0: 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a  SIZE_HINT]..**.*
c9e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c9f0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
ca00: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68  IC_WRITE]].** Th
ca10: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ca20: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
ca30: 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75 73  ITE] opcode caus
ca40: 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20  es all write.** 
ca50: 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63 65  operations since
ca60: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 75   the previous su
ca70: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
ca80: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e   .** [SQLITE_FCN
ca90: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
caa0: 57 52 49 54 45 5d 20 74 6f 20 62 65 20 70 65 72  WRITE] to be per
cab0: 66 6f 72 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c  formed atomicall
cac0: 79 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  y..** This file 
cad0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
cae0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61  [SQLITE_OK] if a
caf0: 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 77  nd only if the w
cb00: 72 69 74 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c  rites were.** al
cb10: 6c 20 70 65 72 66 6f 72 6d 65 64 20 73 75 63 63  l performed succ
cb20: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 68 61 76  essfully and hav
cb30: 65 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  e been committed
cb40: 20 74 6f 20 70 65 72 73 69 73 74 65 6e 74 20 73   to persistent s
cb50: 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61  torage..** ^Rega
cb60: 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
cb70: 72 20 6f 72 20 6e 6f 74 20 69 74 20 69 73 20 73  r or not it is s
cb80: 75 63 63 65 73 73 66 75 6c 2c 20 74 68 69 73 20  uccessful, this 
cb90: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b  file control tak
cba0: 65 73 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64  es.** the file d
cbb0: 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f 66  escriptor out of
cbc0: 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f 64   batch write mod
cbd0: 65 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75  e so that all su
cbe0: 62 73 65 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74  bsequent.** writ
cbf0: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  e operations are
cc00: 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a   independent..**
cc10: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
cc20: 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54  ver invoke SQLIT
cc30: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
cc40: 54 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68  TOMIC_WRITE with
cc50: 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73  out.** a prior s
cc60: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
cc70: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
cc80: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cc90: 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  TE]..**.** <li>[
cca0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f  [SQLITE_FCNTL_RO
ccb0: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
ccc0: 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ITE]].** The [SQ
ccd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
cce0: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
ccf0: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  ] opcode causes 
cd00: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65  all write.** ope
cd10: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68  rations since th
cd20: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65  e previous succe
cd30: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
cd40: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
cd50: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cd60: 54 45 5d 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64  TE] to be rolled
cd70: 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20   back..** ^This 
cd80: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b  file control tak
cd90: 65 73 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  es the file desc
cda0: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61  riptor out of ba
cdb0: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a  tch write mode.*
cdc0: 2a 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75  * so that all su
cdd0: 62 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f  bsequent write o
cde0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e  perations are in
cdf0: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53  dependent..** ^S
ce00: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
ce10: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46   invoke SQLITE_F
ce20: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
ce30: 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f  OMIC_WRITE witho
ce40: 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75  ut.** a prior su
ce50: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
ce60: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
ce70: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
ce80: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  E]..**.** <li>[[
ce90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
cea0: 4b 5f 54 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54  K_TIMEOUT]].** T
ceb0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cec0: 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f  _LOCK_TIMEOUT] o
ced0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 74 74  pcode causes att
cee0: 65 6d 70 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a  empts to obtain.
cef0: 2a 2a 20 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75  ** a file lock u
cf00: 73 69 6e 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f  sing the xLock o
cf10: 72 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  r xShmLock metho
cf20: 64 73 20 6f 66 20 74 68 65 20 56 46 53 20 74 6f  ds of the VFS to
cf30: 20 77 61 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20   wait.** for up 
cf40: 74 6f 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  to M millisecond
cf50: 73 20 62 65 66 6f 72 65 20 66 61 69 6c 69 6e 67  s before failing
cf60: 2c 20 77 68 65 72 65 20 4d 20 69 73 20 74 68 65  , where M is the
cf70: 20 73 69 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69   single .** unsi
cf80: 67 6e 65 64 20 69 6e 74 65 67 65 72 20 70 61 72  gned integer par
cf90: 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ameter..**.** <l
cfa0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
cfb0: 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a  _DATA_VERSION]].
cfc0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
cfd0: 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f  CNTL_DATA_VERSIO
cfe0: 4e 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  N] opcode is use
cff0: 64 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  d to detect chan
d000: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61  ges to.** a data
d010: 62 61 73 65 20 66 69 6c 65 2e 20 20 54 68 65 20  base file.  The 
d020: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
d030: 69 6e 74 65 72 20 74 6f 20 61 20 33 32 2d 62 69  inter to a 32-bi
d040: 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
d050: 65 72 2e 0a 2a 2a 20 54 68 65 20 22 64 61 74 61  er..** The "data
d060: 20 76 65 72 73 69 6f 6e 22 20 66 6f 72 20 74 68   version" for th
d070: 65 20 70 61 67 65 72 20 69 73 20 77 72 69 74 74  e pager is writt
d080: 65 6e 20 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e  en into the poin
d090: 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61  ter.  The.** "da
d0a0: 74 61 20 76 65 72 73 69 6f 6e 22 20 63 68 61 6e  ta version" chan
d0b0: 67 65 73 20 77 68 65 6e 65 76 65 72 20 61 6e 79  ges whenever any
d0c0: 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73 20 74   change occurs t
d0d0: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
d0e0: 69 6e 67 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ing.** database 
d0f0: 66 69 6c 65 2c 20 65 69 74 68 65 72 20 74 68 72  file, either thr
d100: 6f 75 67 68 20 53 51 4c 20 73 74 61 74 65 6d 65  ough SQL stateme
d110: 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  nts on the same 
d120: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
d130: 65 63 74 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67  ection or throug
d140: 68 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  h transactions c
d150: 6f 6d 6d 69 74 74 65 64 20 62 79 20 73 65 70 61  ommitted by sepa
d160: 72 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  rate database.**
d170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73   connections pos
d180: 73 69 62 6c 79 20 69 6e 20 6f 74 68 65 72 20 70  sibly in other p
d190: 72 6f 63 65 73 73 65 73 2e 20 54 68 65 20 5b 73  rocesses. The [s
d1a0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
d1b0: 6e 67 65 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  nges()].** inter
d1c0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
d1d0: 20 74 6f 20 66 69 6e 64 20 69 66 20 61 6e 79 20   to find if any 
d1e0: 64 61 74 61 62 61 73 65 20 6f 6e 20 74 68 65 20  database on the 
d1f0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 63  connection has c
d200: 68 61 6e 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74  hanged,.** but t
d210: 68 61 74 20 69 6e 74 65 72 66 61 63 65 20 72 65  hat interface re
d220: 73 70 6f 6e 64 73 20 74 6f 20 63 68 61 6e 67 65  sponds to change
d230: 73 20 6f 6e 20 54 45 4d 50 20 61 73 20 77 65 6c  s on TEMP as wel
d240: 6c 20 61 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f  l as MAIN and do
d250: 65 73 0a 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64  es.** not provid
d260: 65 20 61 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f  e a mechanism to
d270: 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20   detect changes 
d280: 74 6f 20 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41  to MAIN only.  A
d290: 6c 73 6f 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  lso, the.** [sql
d2a0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
d2b0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
d2c0: 72 65 73 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65  responds to inte
d2d0: 72 6e 61 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c  rnal changes onl
d2e0: 79 20 61 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63  y and.** omits c
d2f0: 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 20 6f  hanges made by o
d300: 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f  ther database co
d310: 6e 6e 65 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  nnections.  The.
d320: 2a 2a 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f  ** [PRAGMA data_
d330: 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64  version] command
d340: 20 70 72 6f 76 69 64 65 20 61 20 6d 65 63 68 61   provide a mecha
d350: 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63  nism to detect c
d360: 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73  hanges to.** a s
d370: 69 6e 67 6c 65 20 61 74 74 61 63 68 65 64 20 64  ingle attached d
d380: 61 74 61 62 61 73 65 20 74 68 61 74 20 6f 63 63  atabase that occ
d390: 75 72 20 64 75 65 20 74 6f 20 6f 74 68 65 72 20  ur due to other 
d3a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d3b0: 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69  ions,.** but omi
d3c0: 74 73 20 63 68 61 6e 67 65 73 20 69 6d 70 6c 65  ts changes imple
d3d0: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 64 61  mented by the da
d3e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d3f0: 6e 20 6f 6e 20 77 68 69 63 68 20 69 74 20 69 73  n on which it is
d400: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 54 68 69  .** called.  Thi
d410: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
d420: 73 20 74 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61  s the only mecha
d430: 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63  nism to detect c
d440: 68 61 6e 67 65 73 20 74 68 61 74 0a 2a 2a 20 68  hanges that.** h
d450: 61 70 70 65 6e 20 65 69 74 68 65 72 20 69 6e 74  appen either int
d460: 65 72 6e 61 6c 6c 79 20 6f 72 20 65 78 74 65 72  ernally or exter
d470: 6e 61 6c 6c 79 20 61 6e 64 20 74 68 61 74 20 61  nally and that a
d480: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
d490: 74 68 0a 2a 2a 20 61 20 70 61 72 74 69 63 75 6c  th.** a particul
d4a0: 61 72 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ar attached data
d4b0: 62 61 73 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  base..** </ul>.*
d4c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d4d0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
d4e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
d4f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d500: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
d510: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a  OXYFILE       2.
d520: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d530: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
d540: 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23  XYFILE       3.#
d550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d560: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  NTL_LAST_ERRNO  
d570: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
d580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d590: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
d5a0: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
d5b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d5c0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
d5d0: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
d5e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d5f0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
d600: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
d610: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d620: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
d630: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
d640: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
d650: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
d660: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
d670: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
d680: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
d690: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
d6a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
d6b0: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
d6c0: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
d6d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
d6e0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
d6f0: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
d700: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
d710: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
d720: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
d730: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
d740: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d750: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
d760: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
d770: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
d780: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
d790: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
d7a0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
d7b0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
d7c0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
d7d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
d7e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d7f0: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
d800: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
d810: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d820: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20  CNTL_HAS_MOVED  
d830: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23              20.#
d840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d850: 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20  NTL_SYNC        
d860: 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64             21.#d
d870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d880: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
d890: 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65  WO        22.#de
d8a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d8b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
d8c0: 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66  LE       23.#def
d8d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d8e0: 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20  _WAL_BLOCK      
d8f0: 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69          24.#defi
d900: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d910: 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20  ZIPVFS          
d920: 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e         25.#defin
d930: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
d940: 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20  BU              
d950: 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65        26.#define
d960: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
d970: 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  S_POINTER       
d980: 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20       27.#define 
d990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
d9a0: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20  RNAL_POINTER    
d9b0: 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53      28.#define S
d9c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d9d0: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_GET_HANDLE    
d9e0: 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51     29.#define SQ
d9f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20  LITE_FCNTL_PDB  
da00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
da10: 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    30.#define SQL
da20: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
da30: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
da40: 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   31.#define SQLI
da50: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
da60: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
da70: 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  32.#define SQLIT
da80: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
da90: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 33  _ATOMIC_WRITE  3
daa0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
dab0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45  _FCNTL_LOCK_TIME
dac0: 4f 55 54 20 20 20 20 20 20 20 20 20 20 20 33 34  OUT           34
dad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dae0: 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49  FCNTL_DATA_VERSI
daf0: 4f 4e 20 20 20 20 20 20 20 20 20 20 20 33 35 0a  ON           35.
db00: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
db10: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
db20: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
db30: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
db40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
db50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
db60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
db70: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
db80: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
db90: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
dba0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
dbb0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
dbc0: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
dbd0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
dbe0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
dbf0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
dc00: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
dc10: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
dc20: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
dc30: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
dc40: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
dc50: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
dc60: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
dc70: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
dc80: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
dc90: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
dca0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
dcb0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
dcc0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
dcd0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
dce0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
dcf0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
dd00: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
dd10: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
dd20: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
dd30: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
dd40: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
dd50: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
dd60: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
dd70: 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65  PI3REF: Loadable
dd80: 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b   Extension Thunk
dd90: 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
dda0: 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73   to the opaque s
ddb0: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
ddc0: 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73  nes structure is
ddd0: 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
dde0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
ddf0: 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74  r to entry point
de00: 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65  s of [loadable e
de10: 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69  xtensions].  Thi
de20: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d  s.** structure m
de30: 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64  ust be typedefed
de40: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72   in order to wor
de50: 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65  k around compile
de60: 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e  r warnings.** on
de70: 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e   some platforms.
de80: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
de90: 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
dea0: 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f  outines sqlite3_
deb0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f  api_routines;../
dec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
ded0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
dee0: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
def0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
df00: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
df10: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
df20: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
df30: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
df40: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
df50: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
df60: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
df70: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
df80: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
df90: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
dfa0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
dfb0: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
dfc0: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
dfd0: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
dfe0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
dff0: 0a 2a 2a 20 54 68 65 20 56 46 53 20 69 6e 74 65  .** The VFS inte
e000: 72 66 61 63 65 20 69 73 20 73 6f 6d 65 74 69 6d  rface is sometim
e010: 65 73 20 65 78 74 65 6e 64 65 64 20 62 79 20 61  es extended by a
e020: 64 64 69 6e 67 20 6e 65 77 20 6d 65 74 68 6f 64  dding new method
e030: 73 20 6f 6e 74 6f 0a 2a 2a 20 74 68 65 20 65 6e  s onto.** the en
e040: 64 2e 20 20 45 61 63 68 20 74 69 6d 65 20 73 75  d.  Each time su
e050: 63 68 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20  ch an extension 
e060: 6f 63 63 75 72 73 2c 20 74 68 65 20 69 56 65 72  occurs, the iVer
e070: 73 69 6f 6e 20 66 69 65 6c 64 0a 2a 2a 20 69 73  sion field.** is
e080: 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 20 20 54   incremented.  T
e090: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
e0a0: 65 20 73 74 61 72 74 65 64 20 6f 75 74 20 61 73  e started out as
e0b0: 20 31 20 69 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   1 in.** SQLite 
e0c0: 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 5d 20  [version 3.5.0] 
e0d0: 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 35 2e 30  on [dateof:3.5.0
e0e0: 5d 2c 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65  ], then increase
e0f0: 64 20 74 6f 20 32 0a 2a 2a 20 77 69 74 68 20 53  d to 2.** with S
e100: 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33  QLite [version 3
e110: 2e 37 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66  .7.0] on [dateof
e120: 3a 33 2e 37 2e 30 5d 2c 20 61 6e 64 20 74 68 65  :3.7.0], and the
e130: 6e 20 69 6e 63 72 65 61 73 65 64 0a 2a 2a 20 74  n increased.** t
e140: 6f 20 33 20 77 69 74 68 20 53 51 4c 69 74 65 20  o 3 with SQLite 
e150: 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 36 5d 20  [version 3.7.6] 
e160: 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 36  on [dateof:3.7.6
e170: 5d 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  ].  Additional f
e180: 69 65 6c 64 73 0a 2a 2a 20 6d 61 79 20 62 65 20  ields.** may be 
e190: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65 20  appended to the 
e1a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
e1b0: 63 74 20 61 6e 64 20 74 68 65 20 69 56 65 72 73  ct and the iVers
e1c0: 69 6f 6e 20 76 61 6c 75 65 0a 2a 2a 20 6d 61 79  ion value.** may
e1d0: 20 69 6e 63 72 65 61 73 65 20 61 67 61 69 6e 20   increase again 
e1e0: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
e1f0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
e200: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
e210: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
e220: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
e230: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
e240: 20 74 68 65 20 74 72 61 6e 73 69 74 69 6f 6e 20   the transition 
e250: 66 72 6f 6d 0a 2a 2a 20 53 51 4c 69 74 65 20 5b  from.** SQLite [
e260: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 5d 20 74  version 3.5.9] t
e270: 6f 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 30  o [version 3.6.0
e280: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 36  ] on [dateof:3.6
e290: 2e 30 5d 0a 2a 2a 20 61 6e 64 20 79 65 74 20 74  .0].** and yet t
e2a0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
e2b0: 64 20 77 61 73 20 6e 6f 74 20 6d 6f 64 69 66 69  d was not modifi
e2c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
e2d0: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
e2e0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
e2f0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
e300: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
e310: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
e320: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
e330: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
e340: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
e350: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
e360: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
e370: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
e380: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
e390: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
e3a0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
e3b0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
e3c0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
e3d0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
e3e0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
e3f0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
e400: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
e410: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
e420: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
e430: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
e440: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
e450: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
e460: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
e470: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
e480: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
e490: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
e4a0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
e4b0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
e4c0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
e4d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
e4e0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
e4f0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
e500: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
e510: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
e520: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
e530: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
e540: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
e550: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
e560: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
e570: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
e580: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
e590: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
e5a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
e5b0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
e5c0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
e5d0: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
e5e0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
e5f0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
e600: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
e610: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
e620: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
e630: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
e640: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
e650: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
e660: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
e670: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
e680: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
e690: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
e6a0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
e6b0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
e6c0: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
e6d0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
e6e0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
e6f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
e700: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
e710: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
e720: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
e730: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
e740: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
e750: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
e760: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
e770: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
e780: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
e790: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
e7a0: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
e7b0: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
e7c0: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
e7d0: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
e7e0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
e7f0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
e800: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
e810: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
e820: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
e830: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
e840: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
e850: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
e860: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
e870: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
e880: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
e890: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
e8a0: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
e8b0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
e8c0: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
e8d0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
e8e0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
e8f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
e900: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
e910: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
e920: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
e930: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
e940: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
e950: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
e960: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
e970: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
e980: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
e990: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
e9a0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
e9b0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
e9c0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
e9d0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e9e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
e9f0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
ea00: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
ea10: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
ea20: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
ea30: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
ea40: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
ea50: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
ea60: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
ea70: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
ea80: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
ea90: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
eaa0: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
eab0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
eac0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
ead0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
eae0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
eaf0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
eb00: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
eb10: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
eb20: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
eb30: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
eb40: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
eb50: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
eb60: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
eb70: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
eb80: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
eb90: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
eba0: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
ebb0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
ebc0: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
ebd0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
ebe0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
ebf0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
ec00: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ec10: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
ec20: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ec30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
ec40: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
ec50: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
ec60: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
ec70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
ec80: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
ec90: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
eca0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
ecb0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ecc0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
ecd0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ece0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
ecf0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
ed00: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
ed10: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
ed20: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
ed30: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
ed40: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
ed50: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
ed60: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
ed70: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
ed80: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
ed90: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
eda0: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
edb0: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
edc0: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
edd0: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
ede0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
edf0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
ee00: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
ee10: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
ee20: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
ee30: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
ee40: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
ee50: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
ee60: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
ee70: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
ee80: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
ee90: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
eea0: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
eeb0: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
eec0: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
eed0: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
eee0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
eef0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
ef00: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
ef10: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
ef20: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ef30: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ef40: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ef50: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
ef60: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
ef70: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
ef80: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
ef90: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
efa0: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
efb0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
efc0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
efd0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
efe0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
eff0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
f000: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
f010: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
f020: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
f030: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
f040: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
f050: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
f060: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
f070: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
f080: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
f090: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
f0a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
f0b0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
f0c0: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
f0d0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
f0e0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
f0f0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
f100: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
f110: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
f120: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
f130: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
f140: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
f150: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
f160: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
f170: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
f180: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
f190: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
f1a0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
f1b0: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
f1c0: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
f1d0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
f1e0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
f1f0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
f200: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
f210: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
f220: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
f230: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
f240: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
f250: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
f260: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
f270: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
f280: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
f290: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
f2a0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
f2b0: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
f2c0: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
f2d0: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
f2e0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
f2f0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
f300: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
f310: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
f320: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
f330: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
f340: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
f350: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
f360: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
f370: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
f380: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
f390: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
f3a0: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
f3b0: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
f3c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
f3d0: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
f3e0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
f3f0: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
f400: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
f410: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
f420: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
f430: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
f440: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
f450: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
f460: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
f470: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
f480: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
f490: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
f4a0: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
f4b0: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
f4c0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
f4d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
f4e0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
f4f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
f500: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
f510: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
f520: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
f530: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
f540: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
f550: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
f560: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
f570: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
f580: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
f590: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
f5a0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
f5b0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
f5c0: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
f5d0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
f5e0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
f5f0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
f600: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
f610: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
f620: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
f630: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
f640: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
f650: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
f660: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
f670: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
f680: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
f690: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
f6a0: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
f6b0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
f6c0: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
f6d0: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
f6e0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
f6f0: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
f700: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
f710: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
f720: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
f730: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
f740: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
f750: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
f760: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
f770: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
f780: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
f790: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
f7a0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
f7b0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
f7c0: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
f7d0: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
f7e0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
f7f0: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
f800: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
f810: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
f820: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
f830: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
f840: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
f850: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
f860: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
f870: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
f880: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
f890: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
f8a0: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
f8b0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
f8c0: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
f8d0: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
f8e0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
f8f0: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
f900: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
f910: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
f920: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
f930: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
f940: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
f950: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
f960: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
f970: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
f980: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
f990: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
f9a0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
f9b0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
f9c0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
f9d0: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
f9e0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
f9f0: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
fa00: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
fa10: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
fa20: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
fa30: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
fa40: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
fa50: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
fa60: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
fa70: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
fa80: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
fa90: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
faa0: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
fab0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
fac0: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
fad0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
fae0: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
faf0: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
fb00: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
fb10: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
fb20: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
fb30: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
fb40: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
fb50: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
fb60: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
fb70: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
fb80: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
fb90: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
fba0: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
fbb0: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
fbc0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
fbd0: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
fbe0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
fbf0: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
fc00: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
fc10: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
fc20: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
fc30: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
fc40: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
fc50: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
fc60: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
fc70: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
fc80: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
fc90: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
fca0: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
fcb0: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
fcc0: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
fcd0: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
fce0: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
fcf0: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
fd00: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
fd10: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
fd20: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
fd30: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
fd40: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
fd50: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
fd60: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
fd70: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
fd80: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
fd90: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
fda0: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
fdb0: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
fdc0: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
fdd0: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
fde0: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
fdf0: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
fe00: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
fe10: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
fe20: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
fe30: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
fe40: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
fe50: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
fe60: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
fe70: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
fe80: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
fe90: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
fea0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
feb0: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
fec0: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
fed0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
fee0: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
fef0: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
ff00: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
ff10: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
ff20: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
ff30: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
ff40: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
ff50: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
ff60: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
ff70: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
ff80: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
ff90: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
ffa0: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
ffb0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
ffc0: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
ffd0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
ffe0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
fff0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
10000 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
10010 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
10020 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
10030 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
10040 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
10050 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
10060 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
10070 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
10080 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
10090 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
100a0 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
100b0 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
100c0 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
100d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
100e0 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
100f0 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
10100 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
10110 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
10120 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
10130 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
10140 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
10150 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
10160 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
10170 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
10180 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
10190 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
101a0 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
101b0 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
101c0 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
101d0 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
101e0 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
101f0 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
10200 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
10210 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10220 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
10230 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
10240 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
10250 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
10260 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
10270 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
10280 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
10290 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
102a0 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
102b0 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
102c0 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
102d0 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
102e0 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
102f0 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
10300 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
10310 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
10320 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
10330 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
10340 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
10350 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
10360 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10370 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
10380 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
10390 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
103a0 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
103b0 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
103c0 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
103d0 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
103e0 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
103f0 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
10400 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
10410 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
10420 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
10430 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
10440 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
10450 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
10460 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
10470 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
10480 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
10490 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
104a0 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
104b0 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
104c0 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
104d0 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
104e0 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
104f0 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
10500 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
10510 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10520 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10530 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
10540 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
10550 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
10560 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
10570 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10580 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
10590 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
105a0 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
105b0 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
105c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
105d0 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
105e0 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
105f0 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
10600 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
10610 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
10620 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
10630 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
10640 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65  pended in future
10650 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
10660 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
10670 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
10680 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
10690 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
106a0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
106b0 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
106c0 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
106d0 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
106e0 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
106f0 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
10700 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
10710 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
10720 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
10730 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
10740 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
10750 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
10760 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
10770 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
10780 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
10790 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
107a0 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
107b0 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
107c0 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
107d0 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
107e0 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
107f0 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
10800 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10810 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
10820 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
10830 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
10840 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
10850 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
10860 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
10870 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
10880 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
10890 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
108a0 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
108b0 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
108c0 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
108d0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
108e0 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
108f0 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
10900 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
10910 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
10920 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
10930 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
10940 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
10950 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
10960 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
10970 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
10980 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
10990 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
109a0 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
109b0 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
109c0 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
109d0 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
109e0 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
109f0 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
10a00 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
10a10 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
10a20 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
10a30 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
10a40 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
10a50 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
10a60 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10a70 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
10a80 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
10a90 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
10aa0 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
10ab0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10ac0 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
10ad0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
10ae0 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
10af0 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
10b00 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
10b10 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
10b20 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
10b30 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
10b40 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
10b50 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
10b60 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
10b70 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
10b80 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
10b90 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
10ba0 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
10bb0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
10bc0 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
10bd0 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
10be0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
10bf0 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
10c00 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
10c10 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
10c20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
10c30 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
10c40 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
10c50 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10c60 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
10c70 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
10c80 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
10c90 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
10ca0 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
10cb0 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
10cc0 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
10cd0 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
10ce0 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
10cf0 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
10d00 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68   was given on th
10d10 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
10d20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
10d30 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
10d40 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
10d50 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
10d60 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
10d70 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
10d80 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
10d90 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
10da0 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
10db0 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
10dc0 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
10dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10de0 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
10df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10e00 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
10e10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10e20 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
10e30 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
10e40 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
10e50 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
10e60 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
10e70 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
10e80 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
10e90 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
10ea0 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
10eb0 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
10ec0 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
10ed0 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
10ee0 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
10ef0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
10f00 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
10f10 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
10f20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
10f30 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
10f40 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
10f50 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
10f60 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
10f70 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
10f80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
10f90 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
10fa0 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
10fb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
10fc0 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
10fd0 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
10fe0 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
10ff0 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
11000 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
11010 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
11020 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
11030 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
11040 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
11050 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
11060 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
11070 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
11080 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
11090 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
110a0 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
110b0 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
110c0 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
110d0 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
110e0 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
110f0 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
11100 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
11110 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
11120 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
11130 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11140 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
11150 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
11160 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
11170 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
11180 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11190 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
111a0 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
111b0 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
111c0 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
111d0 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
111e0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
111f0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
11200 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
11210 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11220 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
11230 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
11240 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
11250 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11260 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
11270 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
11280 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
11290 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
112a0 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
112b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
112c0 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
112d0 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
112e0 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
112f0 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
11300 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11310 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
11320 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11330 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
11340 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
11350 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11360 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
11370 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
11380 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
11390 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
113a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
113b0 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
113c0 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
113d0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
113e0 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
113f0 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
11400 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
11410 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
11420 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
11430 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
11440 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
11450 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
11460 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
11470 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
11480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11490 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
114a0 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
114b0 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
114c0 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
114d0 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
114e0 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
114f0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11500 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
11510 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
11520 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11530 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
11540 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11550 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
11560 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
11570 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
11580 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
11590 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
115a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
115b0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
115c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
115d0 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
115e0 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
115f0 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
11600 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
11610 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
11620 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
11630 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
11640 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
11650 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
11660 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
11670 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
11680 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
11690 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
116a0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
116b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
116c0 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
116d0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
116e0 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
116f0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
11700 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
11710 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
11720 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
11730 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
11740 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
11750 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
11760 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
11770 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
11780 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
11790 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
117a0 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
117b0 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
117c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
117d0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
117e0 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
117f0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
11800 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
11810 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
11820 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
11830 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
11840 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
11850 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
11860 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
11870 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
11880 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
11890 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
118a0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
118b0 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
118c0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
118d0 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
118e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
118f0 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
11900 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
11910 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
11920 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
11930 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
11940 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
11950 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
11960 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
11970 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
11980 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
11990 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
119a0 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
119b0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
119c0 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
119d0 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
119e0 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
119f0 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
11a00 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
11a10 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
11a20 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
11a30 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
11a40 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
11a50 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
11a60 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
11a70 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
11a80 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
11a90 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
11aa0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
11ab0 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
11ac0 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
11ad0 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
11ae0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
11af0 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
11b00 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
11b10 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
11b20 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
11b30 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
11b40 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
11b50 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
11b60 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
11b70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
11b80 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
11b90 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
11ba0 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
11bb0 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
11bc0 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
11bd0 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
11be0 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
11bf0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
11c00 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
11c10 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
11c20 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
11c30 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
11c40 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
11c50 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
11c60 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
11c70 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
11c80 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
11c90 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
11ca0 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
11cb0 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
11cc0 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
11cd0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
11ce0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
11cf0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11d00 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
11d10 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
11d20 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
11d30 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
11d40 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
11d50 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
11d60 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11d70 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
11d80 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11d90 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
11da0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
11db0 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
11dc0 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
11dd0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
11de0 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
11df0 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
11e00 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
11e10 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
11e20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
11e30 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
11e40 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
11e50 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
11e60 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
11e70 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
11e80 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
11e90 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
11ea0 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
11eb0 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
11ec0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
11ed0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11ee0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
11ef0 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
11f00 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
11f10 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
11f20 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
11f30 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
11f40 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
11f50 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
11f60 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
11f70 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
11f80 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
11f90 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
11fa0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
11fb0 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
11fc0 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
11fd0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
11fe0 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
11ff0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
12000 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
12010 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
12020 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
12030 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
12040 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12050 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
12060 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
12070 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12080 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
12090 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
120a0 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
120b0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
120c0 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
120d0 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
120e0 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
120f0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
12100 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
12110 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
12120 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
12130 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
12140 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
12150 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
12160 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
12170 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
12180 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
12190 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
121a0 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
121b0 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
121c0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
121d0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
121e0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
121f0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
12200 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
12210 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
12220 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
12230 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
12240 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
12250 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
12260 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
12270 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
12280 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
12290 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
122a0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
122b0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
122c0 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
122d0 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
122e0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
122f0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12300 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
12310 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
12320 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
12330 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
12340 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
12350 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
12360 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
12370 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
12380 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
12390 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
123a0 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
123b0 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
123c0 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
123d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
123e0 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
123f0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
12400 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
12410 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
12420 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
12430 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
12440 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12450 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
12460 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
12470 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
12480 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
12490 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
124a0 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
124b0 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
124c0 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
124d0 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
124e0 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
124f0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
12500 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12510 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
12520 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
12530 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
12540 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12550 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
12560 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
12570 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
12580 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
12590 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
125a0 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
125b0 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
125c0 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
125d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
125e0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
125f0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c  or code]..*/.SQL
12600 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
12610 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
12620 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
12630 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
12640 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
12650 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
12660 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
12670 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
12680 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
12690 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
126a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
126b0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
126c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
126d0 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
126e0 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
126f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12700 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
12710 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
12720 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
12730 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
12740 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
12750 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
12760 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
12770 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
12780 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
12790 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
127a0 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
127b0 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
127c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
127d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
127e0 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
127f0 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
12800 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
12810 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
12820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12830 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
12840 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
12850 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
12860 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
12870 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12880 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
12890 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
128a0 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
128b0 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
128c0 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
128d0 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
128e0 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
128f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
12900 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
12910 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
12920 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
12930 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
12940 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
12950 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
12960 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
12970 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
12980 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
12990 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
129a0 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
129b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
129c0 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
129d0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
129e0 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
129f0 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
12a00 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
12a10 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
12a20 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
12a30 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
12a40 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
12a50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12a60 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
12a70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12a80 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
12a90 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12aa0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
12ab0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
12ac0 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
12ad0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12ae0 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
12af0 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
12b00 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
12b10 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
12b20 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
12b30 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
12b40 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
12b50 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
12b60 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
12b70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12b80 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
12b90 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
12ba0 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
12bb0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
12bc0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
12bd0 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
12be0 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
12bf0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
12c00 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
12c10 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
12c20 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
12c30 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
12c40 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
12c50 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
12c60 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
12c70 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
12c80 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
12c90 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12ca0 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
12cb0 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
12cc0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
12cd0 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
12ce0 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
12cf0 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
12d00 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
12d10 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
12d20 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
12d30 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
12d40 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
12d50 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
12d60 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
12d70 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
12d80 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
12d90 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
12da0 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
12db0 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
12dc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
12dd0 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
12de0 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
12df0 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
12e00 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
12e10 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
12e20 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
12e30 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
12e40 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
12e50 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
12e60 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
12e70 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
12e80 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
12e90 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
12ea0 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
12eb0 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
12ec0 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
12ed0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
12ee0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
12ef0 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
12f00 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
12f10 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
12f20 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
12f30 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
12f40 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
12f50 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
12f60 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
12f70 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
12f80 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
12f90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
12fa0 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
12fb0 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
12fc0 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
12fd0 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
12fe0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
12ff0 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
13000 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
13010 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
13020 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
13030 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
13040 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
13050 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
13060 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
13070 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
13080 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
13090 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
130a0 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
130b0 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
130c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
130d0 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
130e0 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
130f0 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
13100 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
13110 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
13120 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
13130 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
13140 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
13150 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
13160 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
13170 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
13180 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
13190 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
131a0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
131b0 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
131c0 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
131d0 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
131e0 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
131f0 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
13200 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
13210 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
13220 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
13230 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
13240 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
13250 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
13260 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
13270 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
13280 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
13290 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
132a0 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
132b0 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
132c0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
132d0 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
132e0 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
132f0 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
13300 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
13310 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
13320 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
13330 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
13340 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
13350 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
13360 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
13370 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
13380 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
13390 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
133a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
133b0 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
133c0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
133d0 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
133e0 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
133f0 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
13400 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
13410 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
13420 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
13430 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
13440 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
13450 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
13460 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
13470 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
13480 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
13490 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
134a0 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
134b0 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
134c0 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
134d0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
134e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
134f0 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
13500 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
13510 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
13520 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
13530 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
13540 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
13550 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
13560 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
13570 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
13580 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
13590 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
135a0 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
135b0 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
135c0 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
135d0 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
135e0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
135f0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
13600 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
13610 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
13620 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
13630 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
13640 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
13650 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13660 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
13670 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
13680 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
13690 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
136a0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
136b0 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
136c0 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
136d0 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
136e0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
136f0 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
13700 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
13710 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
13720 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
13730 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
13740 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
13750 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
13760 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
13770 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
13780 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
13790 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
137a0 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
137b0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
137c0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
137d0 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
137e0 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
137f0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
13800 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
13810 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
13820 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
13830 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
13840 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
13850 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
13860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
13870 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
13880 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
13890 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
138a0 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
138b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
138c0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
138d0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
138e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
138f0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
13900 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
13910 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
13920 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
13930 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
13940 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
13950 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
13960 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
13970 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
13980 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
13990 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
139a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
139b0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
139c0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
139d0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
139e0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
139f0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
13a00 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
13a10 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
13a20 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
13a30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
13a40 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
13a50 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
13a60 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
13a70 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
13a80 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
13a90 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
13aa0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
13ab0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
13ac0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
13ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
13ae0 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
13af0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
13b00 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
13b10 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
13b20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
13b30 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
13b40 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
13b50 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
13b60 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
13b70 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
13b80 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
13b90 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
13ba0 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
13bb0 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
13bc0 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
13bd0 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
13be0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
13bf0 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
13c00 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13c10 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13c20 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13c30 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13c40 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13c50 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
13c60 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
13c70 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
13c80 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13c90 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
13ca0 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
13cb0 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
13cc0 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
13cd0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
13ce0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
13cf0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
13d00 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13d10 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13d20 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
13d30 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
13d40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13d50 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
13d60 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
13d70 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
13d80 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
13d90 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13da0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13db0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
13dc0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13dd0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13de0 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
13df0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
13e00 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
13e10 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
13e20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13e30 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
13e40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
13e50 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
13e60 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
13e70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
13e80 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
13e90 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
13ea0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
13eb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13ec0 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
13ed0 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
13ee0 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
13ef0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
13f00 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
13f10 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
13f20 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
13f30 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
13f40 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
13f50 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
13f60 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13f70 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
13f80 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
13f90 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13fa0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
13fb0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13fc0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13fd0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13fe0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13ff0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
14000 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
14010 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
14020 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
14030 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
14040 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
14050 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14060 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
14070 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
14080 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
14090 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
140a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
140b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
140c0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
140d0 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
140e0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
140f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
14100 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
14110 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
14120 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
14130 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
14140 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14150 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
14160 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
14170 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
14180 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
14190 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
141a0 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
141b0 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
141c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
141d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
141e0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
141f0 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
14200 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
14210 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
14220 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14230 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
14240 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
14250 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
14260 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
14270 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
14280 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
14290 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
142a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
142b0 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
142c0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
142d0 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
142e0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
142f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
14300 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
14310 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
14320 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
14330 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
14340 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
14350 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14360 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14370 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14380 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14390 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
143a0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
143b0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
143c0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
143d0 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
143e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
143f0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
14400 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
14410 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
14420 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
14430 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
14440 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
14450 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
14460 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
14470 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14480 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
14490 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
144a0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
144b0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
144c0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74  ONFIG_MALLOC opt
144d0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
144e0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
144f0 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
14500 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14510 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14520 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
14530 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
14540 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
14550 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
14560 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
14570 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
14580 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
14590 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
145a0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
145b0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
145c0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
145d0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
145e0 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
145f0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
14600 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
14610 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14620 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14630 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
14640 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14650 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
14660 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14680 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
14690 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
146a0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
146b0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
146c0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f  NFIG_GETMALLOC o
146d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
146e0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
146f0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
14700 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
14710 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
14720 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
14730 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
14740 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14750 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
14760 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
14770 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
14780 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
14790 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
147a0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
147b0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
147c0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
147d0 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
147e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
147f0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
14800 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
14810 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
14820 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
14830 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
14840 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
14850 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
14860 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14870 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
14880 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
14890 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41  _CONFIG_SMALL_MA
148a0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
148b0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
148c0 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f  NFIG_SMALL_MALLO
148d0 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  C option takes s
148e0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
148f0 66 0a 2a 2a 20 74 79 70 65 20 69 6e 74 2c 20 69  f.** type int, i
14900 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14910 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 69  boolean, which i
14920 66 20 74 72 75 65 20 70 72 6f 76 69 64 65 73 20  f true provides 
14930 61 20 68 69 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  a hint to.** SQL
14940 69 74 65 20 74 68 61 74 20 69 74 20 73 68 6f 75  ite that it shou
14950 6c 64 20 61 76 6f 69 64 20 6c 61 72 67 65 20 6d  ld avoid large m
14960 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14970 73 20 69 66 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  s if possible..*
14980 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 72 75  * SQLite will ru
14990 6e 20 66 61 73 74 65 72 20 69 66 20 69 74 20 69  n faster if it i
149a0 73 20 66 72 65 65 20 74 6f 20 6d 61 6b 65 20 6c  s free to make l
149b0 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  arge memory allo
149c0 63 61 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20  cations,.** but 
149d0 73 6f 6d 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  some application
149e0 20 6d 69 67 68 74 20 70 72 65 66 65 72 20 74 6f   might prefer to
149f0 20 72 75 6e 20 73 6c 6f 77 65 72 20 69 6e 20 65   run slower in e
14a00 78 63 68 61 6e 67 65 20 66 6f 72 0a 2a 2a 20 67  xchange for.** g
14a10 75 61 72 61 6e 74 65 65 73 20 61 62 6f 75 74 20  uarantees about 
14a20 6d 65 6d 6f 72 79 20 66 72 61 67 6d 65 6e 74 61  memory fragmenta
14a30 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 70 6f  tion that are po
14a40 73 73 69 62 6c 65 20 69 66 20 6c 61 72 67 65 0a  ssible if large.
14a50 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ** allocations a
14a60 72 65 20 61 76 6f 69 64 65 64 2e 20 20 54 68 69  re avoided.  Thi
14a70 73 20 68 69 6e 74 20 69 73 20 6e 6f 72 6d 61 6c  s hint is normal
14a80 6c 79 20 6f 66 66 2e 0a 2a 2a 20 3c 2f 64 64 3e  ly off..** </dd>
14a90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14aa0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
14ab0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14ac0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
14ad0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
14ae0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14af0 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20  EMSTATUS option 
14b00 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
14b10 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
14b20 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65  t,.** interprete
14b30 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
14b40 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
14b50 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
14b60 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d  llection of.** m
14b70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14b80 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
14b90 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
14ba0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14bb0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
14bc0 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
14bd0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
14be0 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
14bf0 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
14c00 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
14c10 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
14c20 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
14c30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
14c40 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
14c50 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14c60 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
14c70 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
14c80 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
14c90 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
14ca0 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
14cb0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14cc0 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
14cd0 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
14ce0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
14cf0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
14d00 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
14d10 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
14d20 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
14d30 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14d40 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
14d50 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
14d60 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
14d70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14d80 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
14d90 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
14da0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  H</dt>.** <dd> T
14db0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14dc0 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
14dd0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  is no longer use
14de0 64 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  d..** </dd>.**.*
14df0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14e00 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
14e10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14e20 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
14e30 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
14e40 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14e50 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  CHE option speci
14e60 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f  fies a memory po
14e70 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  ol.** that SQLit
14e80 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68  e can use for th
14e90 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
14ea0 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
14eb0 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63  efault page.** c
14ec0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
14ed0 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
14ee0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14ef0 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69  ion is a no-op i
14f00 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
14f10 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
14f20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
14f30 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
14f40 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
14f50 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
14f60 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
14f70 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
14f80 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
14f90 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f  _PAGECACHE: A po
14fa0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79  inter to.** 8-by
14fb0 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  te aligned memor
14fc0 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69  y (pMem), the si
14fd0 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
14fe0 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c  cache line (sz),
14ff0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  .** and the numb
15000 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65  er of cache line
15010 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
15020 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
15030 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
15040 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
15050 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
15060 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
15070 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35  ween 512 and 655
15080 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78  36) plus some ex
15090 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61  tra bytes for ea
150a0 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
150b0 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  r.  ^The number 
150c0 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e  of extra bytes n
150d0 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67  eeded by the pag
150e0 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20  e header.** can 
150f0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
15100 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ing [SQLITE_CONF
15110 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
15120 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d  ..** ^It is harm
15130 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
15140 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
15150 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ry,.** for the s
15160 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  z parameter to b
15170 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65  e larger than ne
15180 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d  cessary.  The pM
15190 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  em.** argument m
151a0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
151b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
151c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
151d0 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
151e0 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  d block of memor
151f0 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  y of at least sz
15200 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77  *N bytes, otherw
15210 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e  ise.** subsequen
15220 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  t behavior is un
15230 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65  defined..** ^Whe
15240 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55  n pMem is not NU
15250 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
15260 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68  strive to use th
15270 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
15280 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20  d.** to satisfy 
15290 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73  page cache needs
152a0 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74  , falling back t
152b0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
152c0 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67  c()] if.** a pag
152d0 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20  e cache line is 
152e0 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62  larger than sz b
152f0 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f  ytes or if all o
15300 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65  f the pMem buffe
15310 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65  r.** is exhauste
15320 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69  d..** ^If pMem i
15330 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
15340 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65  non-zero, then e
15350 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
15360 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20  nection.** does 
15370 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20  an initial bulk 
15380 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70  allocation for p
15390 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
153a0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
153b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66  3_malloc()] suff
153c0 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63  icient for N cac
153d0 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73  he lines if N is
153e0 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20   positive or.** 
153f0 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73  of -1024*N bytes
15400 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
15410 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f  e, . ^If additio
15420 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
15430 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
15440 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
15450 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
15460 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c  e initial.** all
15470 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51  ocation, then SQ
15480 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
15490 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
154a0 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65  separately for e
154b0 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  ach.** additiona
154c0 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f  l cache line. </
154d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
154e0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
154f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15500 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
15510 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
15520 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
15530 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
15540 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
15550 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51  ffer .** that SQ
15560 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f  Lite will use fo
15570 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
15580 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
15590 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20  cation needs.** 
155a0 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
155b0 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51  vided for by [SQ
155c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
155d0 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20  CACHE]..** ^The 
155e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
155f0 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  AP option is onl
15600 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
15610 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
15620 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72  d.** with either
15630 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
15640 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c  MEMSYS3] or [SQL
15650 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
15660 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  S5] and returns.
15670 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
15680 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68  ] if invoked oth
15690 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72  erwise..** ^Ther
156a0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
156b0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
156c0 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20  CONFIG_HEAP:.** 
156d0 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
156e0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
156f0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
15700 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
15710 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
15720 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
15730 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
15740 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
15750 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
15760 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
15770 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
15780 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
15790 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
157a0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
157b0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
157c0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
157d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
157e0 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
157f0 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
15800 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
15810 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
15820 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
15830 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
15840 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  LL then the alte
15850 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
15860 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
15870 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
15880 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
15890 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
158a0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
158b0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
158c0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
158d0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
158e0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
158f0 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
15900 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
15910 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
15920 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
15930 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
15940 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
15950 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
15960 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
15970 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
15980 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
15990 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
159a0 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
159b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
159c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
159d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
159e0 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
159f0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
15a00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15a10 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15a20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15a30 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f  which is a.** po
15a40 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
15a50 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
15a60 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15a70 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
15a80 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
15a90 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61  pecifies alterna
15aa0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
15ab0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
15ac0 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70   be used.** in p
15ad0 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72  lace the mutex r
15ae0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
15af0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
15b00 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
15b10 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
15b20 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
15b30 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15b40 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
15b50 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
15b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
15b70 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
15b80 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
15b90 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
15ba0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15bb0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
15bc0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
15bd0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15be0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
15bf0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
15c00 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
15c10 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
15c20 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
15c30 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
15c40 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
15c50 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15c60 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
15c70 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
15c80 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
15c90 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
15ca0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15cb0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
15cc0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15cd0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
15ce0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15d00 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
15d10 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15d20 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
15d30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15d40 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
15d50 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
15d60 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
15d70 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
15d80 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15d90 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
15da0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
15db0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
15dc0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
15dd0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
15de0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
15df0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
15e00 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
15e10 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
15e20 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
15e30 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
15e40 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
15e50 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
15e60 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
15e70 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
15e80 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
15e90 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15ea0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
15eb0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
15ec0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
15ed0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
15ee0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
15ef0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
15f00 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
15f10 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
15f20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
15f30 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
15f40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15f50 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
15f60 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15f70 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
15f80 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
15f90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
15fa0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
15fb0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15fc0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
15fd0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15fe0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
15ff0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
16000 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16010 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SIDE option take
16020 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
16030 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a  that determine.*
16040 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69  * the default si
16050 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  ze of lookaside 
16060 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b  memory on each [
16070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16080 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
16090 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
160a0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
160b0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
160c0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
160d0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
160e0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
160f0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
16100 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
16110 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51  nection.)^  ^(SQ
16120 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
16130 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68  ASIDE.** sets th
16140 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  e <i>default</i>
16150 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
16160 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
16170 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
16180 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73  .** option to [s
16190 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
161a0 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
161b0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
161c0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
161d0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
161e0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
161f0 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
16200 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16210 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
16220 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16230 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
16240 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
16250 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
16260 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16270 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
16280 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
16290 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
162a0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
162b0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
162c0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
162d0 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72  ies.** the inter
162e0 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d  face to a custom
162f0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
16300 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  ementation.)^.**
16310 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
16320 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
16330 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
16340 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f  hods2] object.</
16350 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16360 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
16370 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
16380 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16390 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
163a0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
163b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
163c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
163d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
163e0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
163f0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
16400 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
16410 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
16420 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a  Lite copies of.*
16430 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61  * the current pa
16440 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
16450 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
16460 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
16470 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16480 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
16490 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
164a0 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
164b0 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
164c0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73  IG_LOG option is
164d0 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
164e0 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  re the SQLite.**
164f0 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c   global [error l
16500 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51  og]..** (^The SQ
16510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16520 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
16530 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
16540 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
16550 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
16560 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
16570 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
16580 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
16590 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
165a0 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
165b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
165c0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
165d0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
165e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
165f0 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
16600 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
16610 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
16620 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
16630 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
16640 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
16650 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
16660 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
16670 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
16680 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
16690 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
166a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
166b0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
166c0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
166d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
166e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
166f0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
16700 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
16710 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
16720 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
16730 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16740 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
16750 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
16760 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
16770 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
16780 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
16790 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
167a0 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
167b0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
167c0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
167d0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
167e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
167f0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
16800 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
16810 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
16820 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
16830 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
16840 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
16850 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
16860 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
16870 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
16880 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
16890 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
168a0 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
168b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
168c0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
168d0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
168e0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
168f0 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
16900 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
16910 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
16920 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
16930 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
16940 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
16950 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16960 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
16970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
16980 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
16990 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f  ITE_CONFIG_URI o
169a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
169b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
169c0 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66   type int..** If
169d0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
169e0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
169f0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
16a00 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
16a10 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74  er is zero,.** t
16a20 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
16a30 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
16a40 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
16a50 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
16a60 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64  bally.** enabled
16a70 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20  , all filenames 
16a80 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
16a90 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
16aa0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
16ab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
16ac0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
16ad0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
16ae0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
16af0 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
16b00 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
16b10 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
16b20 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
16b30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
16b40 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
16b50 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
16b60 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
16b70 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
16b80 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
16b90 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
16ba0 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
16bb0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
16bc0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
16bd0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
16be0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
16bf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16c00 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
16c10 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
16c20 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
16c30 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
16c40 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
16c50 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
16c60 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
16c70 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
16c80 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
16c90 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
16ca0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16cb0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16cc0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
16cd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
16ce0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
16cf0 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  N.** <dd>^The SQ
16d00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
16d10 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
16d20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
16d30 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a  ingle integer.**
16d40 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
16d50 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
16d60 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  s a boolean in o
16d70 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
16d80 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  r disable.** the
16d90 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
16da0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
16db0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
16dc0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
16dd0 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  izer..** ^The de
16de0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
16df0 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
16e00 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
16e10 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
16e20 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
16e30 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
16e40 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
16e50 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
16e60 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
16e70 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
16e80 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
16e90 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
16ea0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
16eb0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
16ec0 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
16ed0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
16ee0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
16ef0 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
16f00 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65  lfunction.** whe
16f10 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
16f20 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
16f30 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
16f40 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
16f50 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
16f60 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
16f70 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
16f80 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
16f90 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
16fa0 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
16fb0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
16fc0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
16fd0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16fe0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
16ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
17000 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
17010 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17020 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
17030 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
17040 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
17050 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
17060 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
17070 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
17080 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
17090 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
170a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
170b0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
170c0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
170d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
170e0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
170f0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17100 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
17110 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
17120 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
17130 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
17140 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
17150 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
17160 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
17170 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
17180 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
17190 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
171a0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
171b0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
171c0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
171d0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
171e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
171f0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
17200 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
17210 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
17220 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
17230 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
17240 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
17250 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
17260 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
17270 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
17280 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
17290 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
172a0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
172b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
172c0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
172d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
172e0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
172f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
17300 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
17310 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
17320 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
17330 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
17340 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
17350 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
17360 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
17370 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
17380 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
17390 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
173a0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
173b0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
173c0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
173d0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
173e0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
173f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
17400 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
17410 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
17420 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
17430 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17440 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
17450 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
17460 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
17470 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
17480 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
17490 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
174a0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
174b0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
174c0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
174d0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
174e0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
174f0 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
17500 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
17510 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
17520 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
17530 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
17540 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
17550 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c  SIZE.** <dd>^SQL
17560 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
17570 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
17580 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
17590 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
175a0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
175b0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
175c0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
175d0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
175e0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
175f0 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
17600 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
17610 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
17620 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  imit..** ^The de
17630 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
17640 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
17650 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
17660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
17670 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
17680 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
17690 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
176a0 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
176b0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
176c0 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
176d0 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78  trol.  ^(The max
176e0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
176f0 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62  p size.** will b
17700 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  e silently trunc
17710 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72  ated if necessar
17720 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65  y so that it doe
17730 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65  s not exceed the
17740 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
17750 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69   maximum mmap si
17760 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  ze set by the.**
17770 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41   [SQLITE_MAX_MMA
17780 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d  P_SIZE] compile-
17790 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a  time option.)^.*
177a0 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67  * ^If either arg
177b0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70  ument to this op
177c0 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65  tion is negative
177d0 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75  , then that argu
177e0 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67  ment is.** chang
177f0 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c  ed to its compil
17800 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
17810 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[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 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
17840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17850 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64  2_HEAPSIZE.** <d
17860 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17870 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17880 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  IZE option is on
17890 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
178a0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
178b0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
178c0 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  s with the [SQLI
178d0 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
178e0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
178f0 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e  acro.** defined.
17900 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   ^SQLITE_CONFIG_
17910 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74  WIN32_HEAPSIZE t
17920 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e  akes a 32-bit un
17930 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76  signed integer v
17940 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65  alue.** that spe
17950 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d  cifies the maxim
17960 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63  um size of the c
17970 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a  reated heap..**.
17980 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17990 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
179a0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
179b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
179c0 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  RSZ.** <dd>^The 
179d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
179e0 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f  ACHE_HDRSZ optio
179f0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
17a00 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
17a10 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
17a20 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
17a30 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74  nd writes into t
17a40 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20  hat integer the 
17a50 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a  number of extra.
17a60 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67  ** bytes per pag
17a70 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  e required for e
17a80 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c  ach page in [SQL
17a90 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
17aa0 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d  ACHE]..** The am
17ab0 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70  ount of extra sp
17ac0 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e  ace required can
17ad0 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e   change dependin
17ae0 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  g on the compile
17af0 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61  r,.** target pla
17b00 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74  tform, and SQLit
17b10 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  e version..**.**
17b20 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17b30 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _PMASZ]].** <dt>
17b40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
17b50 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ASZ.** <dd>^The 
17b60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
17b70 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ASZ option takes
17b80 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
17b90 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
17ba0 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  an unsigned inte
17bb0 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65  ger and sets the
17bc0 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69   "Minimum PMA Si
17bd0 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74  ze" for the mult
17be0 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72  ithreaded.** sor
17bf0 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65  ter to that inte
17c00 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ger.  The defaul
17c10 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69  t minimum PMA Si
17c20 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65  ze is set by the
17c30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54  .** [SQLITE_SORT
17c40 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c  ER_PMASZ] compil
17c50 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20  e-time option.  
17c60 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20  New threads are 
17c70 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68  launched.** to h
17c80 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70  elp with sort op
17c90 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75  erations when mu
17ca0 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74  ltithreaded sort
17cb0 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65  ing.** is enable
17cc0 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52  d (using the [PR
17cd0 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f  AGMA threads] co
17ce0 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61  mmand) and the a
17cf0 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74  mount of content
17d00 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64  .** to be sorted
17d10 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67   exceeds the pag
17d20 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65  e size times the
17d30 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a   minimum of the.
17d40 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65  ** [PRAGMA cache
17d50 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61  _size] setting a
17d60 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a  nd this value..*
17d70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17d80 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
17d90 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  ILL]].** <dt>SQL
17da0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17db0 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64  RNL_SPILL.** <dd
17dc0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17dd0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
17de0 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  LL option takes 
17df0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
17e00 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f  er which.** beco
17e10 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65  mes the [stateme
17e20 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c  nt journal] spil
17e30 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68  l-to-disk thresh
17e40 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65  old.  .** [State
17e50 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61  ment journals] a
17e60 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  re held in memor
17e70 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69  y until their si
17e80 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a  ze (in bytes).**
17e90 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68   exceeds this th
17ea0 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63  reshold, at whic
17eb0 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65  h point they are
17ec0 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
17ed0 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74  ..** Or if the t
17ee0 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20  hreshold is -1, 
17ef0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
17f00 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65  ls are always he
17f10 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c  ld.** exclusivel
17f20 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  y in memory..** 
17f30 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65  Since many state
17f40 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65  ment journals ne
17f50 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65  ver become large
17f60 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70  , setting the sp
17f70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64  ill.** threshold
17f80 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68   to a value such
17f90 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72   as 64KiB can gr
17fa0 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65  eatly reduce the
17fb0 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f   amount of.** I/
17fc0 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75  O required to su
17fd0 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20  pport statement 
17fe0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  rollback..** The
17ff0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
18000 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20  or this setting 
18010 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  is controlled by
18020 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
18030 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20  STMTJRNL_SPILL] 
18040 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
18050 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
18060 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45  ITE_CONFIG_SORTE
18070 52 52 45 46 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  RREF_SIZE]].** <
18080 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
18090 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 0a  _SORTERREF_SIZE.
180a0 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
180b0 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52  E_CONFIG_SORTERR
180c0 45 46 5f 53 49 5a 45 20 6f 70 74 69 6f 6e 20 61  EF_SIZE option a
180d0 63 63 65 70 74 73 20 61 20 73 69 6e 67 6c 65 20  ccepts a single 
180e0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6f 66 20  parameter.** of 
180f0 74 79 70 65 20 28 69 6e 74 29 20 2d 20 74 68 65  type (int) - the
18100 20 6e 65 77 20 76 61 6c 75 65 20 6f 66 20 74 68   new value of th
18110 65 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e  e sorter-referen
18120 63 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c  ce size threshol
18130 64 2e 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 77  d..** Usually, w
18140 68 65 6e 20 53 51 4c 69 74 65 20 75 73 65 73 20  hen SQLite uses 
18150 61 6e 20 65 78 74 65 72 6e 61 6c 20 73 6f 72 74  an external sort
18160 20 74 6f 20 6f 72 64 65 72 20 72 65 63 6f 72 64   to order record
18170 73 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74  s according.** t
18180 6f 20 61 6e 20 4f 52 44 45 52 20 42 59 20 63 6c  o an ORDER BY cl
18190 61 75 73 65 2c 20 61 6c 6c 20 66 69 65 6c 64 73  ause, all fields
181a0 20 72 65 71 75 69 72 65 64 20 62 79 20 74 68 65   required by the
181b0 20 63 61 6c 6c 65 72 20 61 72 65 20 70 72 65 73   caller are pres
181c0 65 6e 74 20 69 6e 20 74 68 65 0a 2a 2a 20 73 6f  ent in the.** so
181d0 72 74 65 64 20 72 65 63 6f 72 64 73 2e 20 48 6f  rted records. Ho
181e0 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
181f0 20 64 65 74 65 72 6d 69 6e 65 73 20 62 61 73 65   determines base
18200 64 20 6f 6e 20 74 68 65 20 64 65 63 6c 61 72 65  d on the declare
18210 64 20 74 79 70 65 0a 2a 2a 20 6f 66 20 61 20 74  d type.** of a t
18220 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
18230 20 69 74 73 20 76 61 6c 75 65 73 20 61 72 65 20   its values are 
18240 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 76 65 72  likely to be ver
18250 79 20 6c 61 72 67 65 20 2d 20 6c 61 72 67 65 72  y large - larger
18260 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 63 6f 6e  .** than the con
18270 66 69 67 75 72 65 64 20 73 6f 72 74 65 72 2d 72  figured sorter-r
18280 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68  eference size th
18290 72 65 73 68 6f 6c 64 20 2d 20 74 68 65 6e 20 61  reshold - then a
182a0 20 72 65 66 65 72 65 6e 63 65 0a 2a 2a 20 69 73   reference.** is
182b0 20 73 74 6f 72 65 64 20 69 6e 20 65 61 63 68 20   stored in each 
182c0 73 6f 72 74 65 64 20 72 65 63 6f 72 64 20 61 6e  sorted record an
182d0 64 20 74 68 65 20 72 65 71 75 69 72 65 64 20 63  d the required c
182e0 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 6c 6f 61  olumn values loa
182f0 64 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ded.** from the 
18300 64 61 74 61 62 61 73 65 20 61 73 20 72 65 63 6f  database as reco
18310 72 64 73 20 61 72 65 20 72 65 74 75 72 6e 65 64  rds are returned
18320 20 69 6e 20 73 6f 72 74 65 64 20 6f 72 64 65 72   in sorted order
18330 2e 20 54 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  . The default.**
18340 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
18350 6f 70 74 69 6f 6e 20 69 73 20 74 6f 20 6e 65 76  option is to nev
18360 65 72 20 75 73 65 20 74 68 69 73 20 6f 70 74 69  er use this opti
18370 6d 69 7a 61 74 69 6f 6e 2e 20 53 70 65 63 69 66  mization. Specif
18380 79 69 6e 67 20 61 20 0a 2a 2a 20 6e 65 67 61 74  ying a .** negat
18390 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
183a0 69 73 20 6f 70 74 69 6f 6e 20 72 65 73 74 6f 72  is option restor
183b0 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 62  es the default b
183c0 65 68 61 76 69 6f 75 72 2e 0a 2a 2a 20 54 68 69  ehaviour..** Thi
183d0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
183e0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
183f0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
18400 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
18410 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 4f 52 54  LITE_ENABLE_SORT
18420 45 52 5f 52 45 46 45 52 45 4e 43 45 53 5d 20 63  ER_REFERENCES] c
18430 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
18440 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  on..** </dl>.*/.
18450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18460 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
18470 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
18480 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18490 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
184a0 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
184b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
184c0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
184d0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
184e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
184f0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
18500 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
18510 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
18520 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18530 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
18540 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
18550 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
18560 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
18570 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
18580 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
18590 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
185a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
185b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
185c0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
185d0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
185e0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
185f0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
18600 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
18610 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
18620 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
18630 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18640 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
18650 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
18660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18670 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
18680 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
18690 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
186a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
186b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
186c0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
186d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
186e0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
186f0 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
18700 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
18710 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
18720 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
18730 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18740 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
18750 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
18760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18770 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
18780 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
18790 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
187a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
187b0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
187c0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
187d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
187e0 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
187f0 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
18800 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18810 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
18820 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
18830 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18840 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
18850 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
18860 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
18870 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
18880 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
18890 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
188a0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
188b0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
188c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
188d0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
188e0 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
188f0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
18900 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
18910 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
18920 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
18930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18940 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
18950 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
18960 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
18970 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
18980 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18990 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
189a0 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
189b0 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
189c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
189d0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
189e0 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
189f0 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  psz */.#define S
18a00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
18a10 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SZ              
18a20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64   25  /* unsigned
18a30 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64   int szPma */.#d
18a40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18a50 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
18a60 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69  LL      26  /* i
18a70 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
18a80 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18a90 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 20  G_SMALL_MALLOC  
18aa0 20 20 20 20 20 20 32 37 20 20 2f 2a 20 62 6f 6f        27  /* boo
18ab0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
18ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f  SQLITE_CONFIG_SO
18ad0 52 54 45 52 52 45 46 5f 53 49 5a 45 20 20 20 20  RTERREF_SIZE    
18ae0 20 20 32 38 20 20 2f 2a 20 69 6e 74 20 6e 42 79    28  /* int nBy
18af0 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  te */../*.** CAP
18b00 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
18b10 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
18b20 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
18b30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
18b40 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
18b50 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
18b60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
18b70 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
18b80 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
18b90 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
18ba0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
18bb0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
18bc0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
18bd0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
18be0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
18bf0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
18c00 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
18c10 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
18c20 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
18c30 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
18c40 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
18c50 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
18c60 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
18c70 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
18c80 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
18c90 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
18ca0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
18cb0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
18cc0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
18cd0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
18ce0 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
18cf0 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
18d00 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
18d10 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
18d20 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
18d30 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
18d40 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
18d50 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
18d60 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18d70 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
18d80 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
18d90 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
18da0 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
18db0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
18dc0 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
18dd0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
18de0 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
18df0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
18e00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
18e10 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
18e20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18e30 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
18e40 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
18e50 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
18e60 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
18e70 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
18e80 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
18e90 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
18ea0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
18eb0 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
18ec0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18ed0 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
18ee0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
18ef0 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
18f00 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
18f10 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
18f20 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
18f30 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
18f40 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
18f50 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
18f60 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
18f70 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
18f80 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
18f90 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
18fa0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
18fb0 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
18fc0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
18fd0 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
18fe0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
18ff0 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
19000 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
19010 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
19020 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
19030 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
19040 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
19050 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
19060 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
19070 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
19080 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
19090 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
190a0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
190b0 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
190c0 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
190d0 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
190e0 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
190f0 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
19100 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
19110 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
19120 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
19130 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
19140 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
19150 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
19160 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
19170 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
19180 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
19190 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
191a0 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
191b0 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
191c0 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
191d0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
191e0 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
191f0 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
19200 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
19210 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
19220 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
19230 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
19240 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
19250 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
19260 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
19270 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
19280 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
19290 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
192a0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
192b0 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
192c0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
192d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
192e0 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
192f0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
19300 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
19310 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
19320 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
19330 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
19340 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
19350 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
19360 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
19370 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
19380 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19390 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
193a0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
193b0 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
193c0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
193d0 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
193e0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
193f0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
19400 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
19410 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
19420 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19430 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
19440 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
19450 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
19460 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
19470 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
19480 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
19490 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
194a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
194b0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
194c0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
194d0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
194e0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
194f0 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
19500 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
19510 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
19520 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
19530 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19540 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
19550 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
19560 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
19570 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
19580 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
19590 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
195a0 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
195b0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
195c0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
195d0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
195e0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
195f0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
19600 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
19610 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
19620 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
19630 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
19640 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
19650 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
19660 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
19670 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
19680 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
19690 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
196a0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
196b0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
196c0 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
196d0 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
196e0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
196f0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
19700 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
19710 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
19720 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
19730 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
19740 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
19750 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
19760 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
19770 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19780 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19790 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
197a0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
197b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
197c0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
197d0 20 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f   disable the two
197e0 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72  -argument.** ver
197f0 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73  sion of the [fts
19800 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66  3_tokenizer()] f
19810 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73  unction which is
19820 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
19830 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74  [FTS3] full-text
19840 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65   search engine e
19850 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65  xtension..** The
19860 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
19870 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
19880 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
19890 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
198a0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
198b0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
198c0 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28   fts3_tokenizer(
198d0 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ) or.** positive
198e0 20 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f   to enable fts3_
198f0 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e  tokenizer() or n
19900 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
19910 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
19920 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
19930 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19940 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
19950 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
19960 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
19970 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
19980 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
19990 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  r fts3_tokenizer
199a0 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20   is disabled or 
199b0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
199c0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
199d0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
199e0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
199f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
19a00 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
19a10 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73  e new setting is
19a20 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
19a30 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
19a40 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
19a50 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f  FIG_ENABLE_LOAD_
19a60 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a  EXTENSION</dt>.*
19a70 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
19a80 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
19a90 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
19aa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
19ab0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  ad_extension()].
19ac0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64  ** interface ind
19ad0 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68  ependently of th
19ae0 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e [load_extensio
19af0 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  n()] SQL functio
19b00 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  n..** The [sqlit
19b10 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
19b20 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20  xtension()] API 
19b30 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
19b40 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20  les both the.** 
19b50 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c  C-API [sqlite3_l
19b60 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
19b70 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
19b80 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65  ction [load_exte
19b90 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65  nsion()]..** The
19ba0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
19bb0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
19bc0 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  ments..** When t
19bd0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19be0 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66  t to this interf
19bf0 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f  ace is 1, then o
19c00 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73  nly the C-API is
19c10 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20  .** enabled and 
19c20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
19c30 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65   remains disable
19c40 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74  d.  If the first
19c50 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
19c60 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
19c70 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74  s 0, then both t
19c80 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65  he C-API and the
19c90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72   SQL function ar
19ca0 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49  e disabled..** I
19cb0 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  f the first argu
19cc0 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e  ment is -1, then
19cd0 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20   no changes are 
19ce0 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66  made to state of
19cf0 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43   either the.** C
19d00 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20  -API or the SQL 
19d10 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
19d20 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19d30 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
19d40 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
19d50 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
19d60 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
19d70 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
19d80 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
19d90 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
19da0 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61  rface.** is disa
19db0 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20  bled or enabled 
19dc0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
19dd0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
19de0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a   parameter may.*
19df0 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * be a NULL poin
19e00 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ter, in which ca
19e10 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
19e20 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
19e30 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64  ed back..** </dd
19e40 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19e50 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
19e60 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBNAME</dt>.** <
19e70 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19e80 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e   is used to chan
19e90 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ge the name of t
19ea0 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61  he "main" databa
19eb0 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e  se.** schema.  ^
19ec0 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e  The sole argumen
19ed0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
19ee0 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46  o a constant UTF
19ef0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63  8 string.** whic
19f00 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  h will become th
19f10 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d  e new schema nam
19f20 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  e in place of "m
19f30 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a  ain".  ^SQLite.*
19f40 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20  * does not make 
19f50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65  a copy of the ne
19f60 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61  w main schema na
19f70 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68  me string, so th
19f80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
19f90 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
19fa0 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  t the argument p
19fb0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20  assed into this 
19fc0 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20  DBCONFIG option 
19fd0 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  is unchanged.** 
19fe0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20  until after the 
19ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a000 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c  ion closes..** <
1a010 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1a020 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e  QLITE_DBCONFIG_N
1a030 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c  O_CKPT_ON_CLOSE<
1a040 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75  /dt>.** <dd> Usu
1a050 61 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74  ally, when a dat
1a060 61 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64  abase in wal mod
1a070 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64  e is closed or d
1a080 65 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a  etached from a .
1a090 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  ** database hand
1a0a0 6c 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b  le, SQLite check
1a0b0 73 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d  s if this will m
1a0c0 65 61 6e 20 74 68 61 74 20 74 68 65 72 65 20 61  ean that there a
1a0d0 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f  re now no .** co
1a0e0 6e 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c  nnections at all
1a0f0 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
1a100 2e 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66  . If so, it perf
1a110 6f 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e  orms a checkpoin
1a120 74 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  t .** operation 
1a130 62 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74  before closing t
1a140 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54  he connection. T
1a150 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62  his option may b
1a160 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65  e used to.** ove
1a170 72 72 69 64 65 20 74 68 69 73 20 62 65 68 61 76  rride this behav
1a180 69 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74 20  iour. The first 
1a190 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
1a1a0 20 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69   to this operati
1a1b0 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  on.** is an inte
1a1c0 67 65 72 20 2d 20 70 6f 73 69 74 69 76 65 20 74  ger - positive t
1a1d0 6f 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70  o disable checkp
1a1e0 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20  oints-on-close, 
1a1f0 6f 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20  or zero (the.** 
1a200 64 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62  default) to enab
1a210 6c 65 20 74 68 65 6d 2c 20 61 6e 64 20 6e 65 67  le them, and neg
1a220 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
1a230 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
1a240 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
1a250 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1a260 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1a270 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f   integer.** into
1a280 20 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65   which is writte
1a290 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
1a2a0 63 61 74 65 20 77 68 65 74 68 65 72 20 63 68 65  cate whether che
1a2b0 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73  ckpoints-on-clos
1a2c0 65 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64  e.** have been d
1a2d0 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74  isabled - 0 if t
1a2e0 68 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61  hey are not disa
1a2f0 62 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79 20  bled, 1 if they 
1a300 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  are..** </dd>.**
1a310 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
1a320 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51  BCONFIG_ENABLE_Q
1a330 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PSG</dt>.** <dd>
1a340 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43  ^(The SQLITE_DBC
1a350 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
1a360 47 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74  G option activat
1a370 65 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65  es or deactivate
1a380 73 0a 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20  s.** the [query 
1a390 70 6c 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74  planner stabilit
1a3a0 79 20 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50  y guarantee] (QP
1a3b0 53 47 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51  SG).  When the Q
1a3c0 50 53 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a  PSG is active,.*
1a3d0 2a 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71  * a single SQL q
1a3e0 75 65 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77  uery statement w
1a3f0 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74  ill always use t
1a400 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
1a410 6d 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  m regardless.** 
1a420 6f 66 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f  of values of [bo
1a430 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e  und parameters].
1a440 29 5e 20 54 68 65 20 51 50 53 47 20 64 69 73 61  )^ The QPSG disa
1a450 62 6c 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20  bles some query 
1a460 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a  optimizations.**
1a470 20 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68   that look at th
1a480 65 20 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e  e values of boun
1a490 64 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68  d parameters, wh
1a4a0 69 63 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d  ich can make som
1a4b0 65 20 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f  e queries.** slo
1a4c0 77 65 72 2e 20 20 42 75 74 20 74 68 65 20 51 50  wer.  But the QP
1a4d0 53 47 20 68 61 73 20 74 68 65 20 61 64 76 61 6e  SG has the advan
1a4e0 74 61 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65  tage of more pre
1a4f0 64 69 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f  dictable behavio
1a500 72 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20  r.  With.** the 
1a510 51 50 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c  QPSG active, SQL
1a520 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
1a530 75 73 65 20 74 68 65 20 73 61 6d 65 20 71 75 65  use the same que
1a540 72 79 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66  ry plan in the f
1a550 69 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75  ield as.** was u
1a560 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
1a570 6e 67 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a  ng in the lab..*
1a580 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1a590 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 73 65 74  ment to this set
1a5a0 74 69 6e 67 20 69 73 20 61 6e 20 69 6e 74 65 67  ting is an integ
1a5b0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
1a5c0 20 64 69 73 61 62 6c 65 20 0a 2a 2a 20 74 68 65   disable .** the
1a5d0 20 51 50 53 47 2c 20 70 6f 73 69 74 69 76 65 20   QPSG, positive 
1a5e0 74 6f 20 65 6e 61 62 6c 65 20 51 50 53 47 2c 20  to enable QPSG, 
1a5f0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
1a600 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
1a610 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 54  .** unchanged. T
1a620 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a630 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1a640 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
1a650 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
1a660 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
1a670 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1a680 65 72 20 74 68 65 20 51 50 53 47 20 69 73 20 64  er the QPSG is d
1a690 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
1a6a0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
1a6b0 74 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f  this call..** </
1a6c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1a6d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52  LITE_DBCONFIG_TR
1a6e0 49 47 47 45 52 5f 45 51 50 3c 2f 64 74 3e 0a 2a  IGGER_EQP</dt>.*
1a6f0 2a 20 3c 64 64 3e 20 42 79 20 64 65 66 61 75 6c  * <dd> By defaul
1a700 74 2c 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  t, the output of
1a710 20 45 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50   EXPLAIN QUERY P
1a720 4c 41 4e 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 65  LAN commands doe
1a730 73 20 6e 6f 74 20 0a 2a 2a 20 69 6e 63 6c 75 64  s not .** includ
1a740 65 20 6f 75 74 70 75 74 20 66 6f 72 20 61 6e 79  e output for any
1a750 20 6f 70 65 72 61 74 69 6f 6e 73 20 70 65 72 66   operations perf
1a760 6f 72 6d 65 64 20 62 79 20 74 72 69 67 67 65 72  ormed by trigger
1a770 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 69 73 0a   programs. This.
1a780 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1a790 64 20 74 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  d to set or clea
1a7a0 72 20 28 74 68 65 20 64 65 66 61 75 6c 74 29 20  r (the default) 
1a7b0 61 20 66 6c 61 67 20 74 68 61 74 20 67 6f 76 65  a flag that gove
1a7c0 72 6e 73 20 74 68 69 73 0a 2a 2a 20 62 65 68 61  rns this.** beha
1a7d0 76 69 6f 72 2e 20 54 68 65 20 66 69 72 73 74 20  vior. The first 
1a7e0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
1a7f0 20 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69   to this operati
1a800 6f 6e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  on is an integer
1a810 20 2d 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74   -.** positive t
1a820 6f 20 65 6e 61 62 6c 65 20 6f 75 74 70 75 74 20  o enable output 
1a830 66 6f 72 20 74 72 69 67 67 65 72 20 70 72 6f 67  for trigger prog
1a840 72 61 6d 73 2c 20 6f 72 20 7a 65 72 6f 20 74 6f  rams, or zero to
1a850 20 64 69 73 61 62 6c 65 20 69 74 2c 0a 2a 2a 20   disable it,.** 
1a860 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
1a870 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
1a880 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
1a890 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a8a0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1a8b0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
1a8c0 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72 69  nto which is wri
1a8d0 74 74 65 6e 20 0a 2a 2a 20 30 20 6f 72 20 31 20  tten .** 0 or 1 
1a8e0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
1a8f0 68 65 72 20 6f 75 74 70 75 74 2d 66 6f 72 2d 74  her output-for-t
1a900 72 69 67 67 65 72 73 20 68 61 73 20 62 65 65 6e  riggers has been
1a910 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66   disabled - 0 if
1a920 20 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 64   .** it is not d
1a930 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 69 74  isabled, 1 if it
1a940 20 69 73 2e 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a   is.  .** </dd>.
1a950 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a960 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1a970 44 41 54 41 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a  DATABASE</dt>.**
1a980 20 3c 64 64 3e 20 53 65 74 20 74 68 65 20 53 51   <dd> Set the SQ
1a990 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45  LITE_DBCONFIG_RE
1a9a0 53 45 54 5f 44 41 54 41 42 41 53 45 20 66 6c 61  SET_DATABASE fla
1a9b0 67 20 61 6e 64 20 74 68 65 6e 20 72 75 6e 0a 2a  g and then run.*
1a9c0 2a 20 5b 56 41 43 55 55 4d 5d 20 69 6e 20 6f 72  * [VACUUM] in or
1a9d0 64 65 72 20 74 6f 20 72 65 73 65 74 20 61 20 64  der to reset a d
1a9e0 61 74 61 62 61 73 65 20 62 61 63 6b 20 74 6f 20  atabase back to 
1a9f0 61 6e 20 65 6d 70 74 79 20 64 61 74 61 62 61 73  an empty databas
1aa00 65 0a 2a 2a 20 77 69 74 68 20 6e 6f 20 73 63 68  e.** with no sch
1aa10 65 6d 61 20 61 6e 64 20 6e 6f 20 63 6f 6e 74 65  ema and no conte
1aa20 6e 74 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  nt. The followin
1aa30 67 20 70 72 6f 63 65 73 73 20 77 6f 72 6b 73 20  g process works 
1aa40 65 76 65 6e 20 66 6f 72 0a 2a 2a 20 61 20 62 61  even for.** a ba
1aa50 64 6c 79 20 63 6f 72 72 75 70 74 65 64 20 64 61  dly corrupted da
1aa60 74 61 62 61 73 65 20 66 69 6c 65 3a 0a 2a 2a 20  tabase file:.** 
1aa70 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
1aa80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1aa90 6e 65 63 74 69 6f 6e 20 69 73 20 6e 65 77 6c 79  nection is newly
1aaa0 20 6f 70 65 6e 65 64 2c 20 6d 61 6b 65 20 73 75   opened, make su
1aab0 72 65 20 69 74 20 68 61 73 20 72 65 61 64 20 74  re it has read t
1aac0 68 65 0a 2a 2a 20 20 20 20 20 20 64 61 74 61 62  he.**      datab
1aad0 61 73 65 20 73 63 68 65 6d 61 20 62 79 20 70 72  ase schema by pr
1aae0 65 70 61 72 69 6e 67 20 74 68 65 6e 20 64 69 73  eparing then dis
1aaf0 63 61 72 64 69 6e 67 20 73 6f 6d 65 20 71 75 65  carding some que
1ab00 72 79 20 61 67 61 69 6e 73 74 20 74 68 65 0a 2a  ry against the.*
1ab10 2a 20 20 20 20 20 20 64 61 74 61 62 61 73 65 2c  *      database,
1ab20 20 6f 72 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   or calling sqli
1ab30 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
1ab40 5f 6d 65 74 61 64 61 74 61 28 29 2c 20 69 67 6e  _metadata(), ign
1ab50 6f 72 69 6e 67 20 61 6e 79 0a 2a 2a 20 20 20 20  oring any.**    
1ab60 20 20 65 72 72 6f 72 73 2e 20 20 54 68 69 73 20    errors.  This 
1ab70 73 74 65 70 20 69 73 20 6f 6e 6c 79 20 6e 65 63  step is only nec
1ab80 65 73 73 61 72 79 20 69 66 20 74 68 65 20 61 70  essary if the ap
1ab90 70 6c 69 63 61 74 69 6f 6e 20 64 65 73 69 72 65  plication desire
1aba0 73 20 74 6f 20 6b 65 65 70 0a 2a 2a 20 20 20 20  s to keep.**    
1abb0 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69    the database i
1abc0 6e 20 57 41 4c 20 6d 6f 64 65 20 61 66 74 65 72  n WAL mode after
1abd0 20 74 68 65 20 72 65 73 65 74 20 69 66 20 69 74   the reset if it
1abe0 20 77 61 73 20 69 6e 20 57 41 4c 20 6d 6f 64 65   was in WAL mode
1abf0 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20   before.**      
1ac00 74 68 65 20 72 65 73 65 74 2e 20 20 0a 2a 2a 20  the reset.  .** 
1ac10 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f  <li> sqlite3_db_
1ac20 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54  config(db, SQLIT
1ac30 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54  E_DBCONFIG_RESET
1ac40 5f 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30 29  _DATABASE, 1, 0)
1ac50 3b 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  ;.** <li> [sqlit
1ac60 65 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b 56  e3_exec](db, "[V
1ac70 41 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20 30  ACUUM]", 0, 0, 0
1ac80 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74  );.** <li> sqlit
1ac90 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c  e3_db_config(db,
1aca0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1acb0 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c  _RESET_DATABASE,
1acc0 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e   0, 0);.** </ol>
1acd0 0a 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73 65  .** Because rese
1ace0 74 74 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  tting a database
1acf0 20 69 73 20 64 65 73 74 72 75 63 74 69 76 65 20   is destructive 
1ad00 61 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c 65  and irreversible
1ad10 2c 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73 73  , the.** process
1ad20 20 72 65 71 75 69 72 65 73 20 74 68 65 20 75 73   requires the us
1ad30 65 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75 72  e of this obscur
1ad40 65 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69 70  e API and multip
1ad50 6c 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c 70  le steps to help
1ad60 0a 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74 20  .** ensure that 
1ad70 69 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70 70  it does not happ
1ad80 65 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e 0a  en by accident..
1ad90 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ** </dd>.** </dl
1ada0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1adb0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
1adc0 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20  NDBNAME         
1add0 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74     1000 /* const
1ade0 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e   char* */.#defin
1adf0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1ae00 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
1ae10 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20          1001 /* 
1ae20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
1ae30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ae40 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1ae50 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31  FKEY           1
1ae60 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  002 /* int int* 
1ae70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ae80 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1ae90 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1aea0 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74   1003 /* int int
1aeb0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1aec0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1aed0 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
1aee0 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69  ER 1004 /* int i
1aef0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1af00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1af10 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
1af20 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74  SION 1005 /* int
1af30 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1af40 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1af50 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53  _NO_CKPT_ON_CLOS
1af60 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69  E      1006 /* i
1af70 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1af80 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1af90 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20  IG_ENABLE_QPSG  
1afa0 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a           1007 /*
1afb0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1afc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1afd0 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
1afe0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20             1008 
1aff0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1b000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1b010 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1b020 41 42 41 53 45 20 20 20 20 20 20 20 20 31 30 30  ABASE        100
1b030 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  9 /* int int* */
1b040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b050 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20  DBCONFIG_MAX    
1b060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1b070 30 30 39 20 2f 2a 20 4c 61 72 67 65 73 74 20 44  009 /* Largest D
1b080 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a  BCONFIG */../*.*
1b090 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
1b0a0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
1b0b0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
1b0c0 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
1b0d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1b0e0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
1b0f0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
1b100 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
1b110 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
1b120 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
1b130 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
1b140 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
1b150 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
1b160 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
1b170 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
1b180 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
1b190 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
1b1a0 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ty..*/.SQLITE_AP
1b1b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
1b1c0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
1b1d0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
1b1e0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
1b1f0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
1b200 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20  Insert Rowid.** 
1b210 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1b220 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
1b230 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
1b240 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
1b250 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
1b260 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
1b270 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
1b280 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
1b290 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
1b2a0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
1b2b0 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
1b2c0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
1b2d0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
1b2e0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
1b2f0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
1b300 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
1b310 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
1b320 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
1b330 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
1b340 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1b350 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
1b360 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
1b370 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
1b380 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
1b390 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
1b3a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
1b3b0 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
1b3c0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
1b3d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
1b3e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1b3f0 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 61  ) interface usua
1b400 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
1b410 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68  [rowid] of.** th
1b420 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  e most recent su
1b430 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
1b440 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
1b450 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
1b460 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
1b470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b480 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e  n D. ^Inserts in
1b490 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
1b4a0 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
1b4b0 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e  t.** recorded. ^
1b4c0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
1b4d0 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
1b4e0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 76  rowid tables hav
1b4f0 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
1b500 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 62  .** on the datab
1b510 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1b520 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  , then sqlite3_l
1b530 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1b540 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  (D) returns .** 
1b550 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  zero..**.** As w
1b560 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 74  ell as being set
1b570 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
1b580 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 72  s rows are inser
1b590 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 73  ted into databas
1b5a0 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 65  e.** tables, the
1b5b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b5c0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
1b5d0 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 6c   may be set expl
1b5e0 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71  icitly by.** [sq
1b5f0 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1b600 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1b610 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 61  *.** Some virtua
1b620 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
1b630 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45  tations may INSE
1b640 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77  RT rows into row
1b650 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20  id tables as.** 
1b660 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69  part of committi
1b670 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
1b680 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20   (e.g. to flush 
1b690 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 64  data accumulated
1b6a0 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f   in memory.** to
1b6b0 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 20   disk). In this 
1b6c0 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 20  case subsequent 
1b6d0 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 75  calls to this fu
1b6e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 68  nction return th
1b6f0 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63  e rowid.** assoc
1b700 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73 65  iated with these
1b710 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 54   internal INSERT
1b720 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 69   operations, whi
1b730 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20  ch leads to .** 
1b740 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 75  unintuitive resu
1b750 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 62  lts. Virtual tab
1b760 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1b770 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 65  ns that do write
1b780 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62   to rowid.** tab
1b790 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 20  les in this way 
1b7a0 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 70  can avoid this p
1b7b0 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f 72  roblem by restor
1b7c0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
1b7d0 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 65   .** rowid value
1b7e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b7f0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1b800 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 20  rowid()] before 
1b810 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f  returning .** co
1b820 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 65  ntrol to the use
1b830 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  r..**.** ^(If an
1b840 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
1b850 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1b860 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  r then this rout
1b870 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74  ine will .** ret
1b880 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
1b890 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 20  of the inserted 
1b8a0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
1b8b0 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a 2a  he trigger is .*
1b8c0 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20  * running. Once 
1b8d0 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67  the trigger prog
1b8e0 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 61  ram ends, the va
1b8f0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
1b900 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
1b910 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
1b920 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
1b930 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20 66  he trigger was f
1b940 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  ired.)^.**.** ^A
1b950 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
1b960 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
1b970 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
1b980 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
1b990 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1b9a0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
1b9b0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
1b9c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
1b9d0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
1b9e0 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
1b9f0 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
1ba00 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
1ba10 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
1ba20 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
1ba30 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
1ba40 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
1ba50 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
1ba60 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
1ba70 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
1ba80 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
1ba90 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
1baa0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
1bab0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
1bac0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
1bad0 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
1bae0 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
1baf0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
1bb00 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
1bb10 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
1bb20 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
1bb30 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
1bb40 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
1bb50 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
1bb60 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
1bb70 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
1bb80 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
1bb90 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
1bba0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
1bbb0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
1bbc0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
1bbd0 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
1bbe0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
1bbf0 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
1bc00 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
1bc10 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
1bc20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
1bc30 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
1bc40 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
1bc50 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
1bc60 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1bc70 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1bc80 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
1bc90 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
1bca0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
1bcb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bcc0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
1bcd0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1bce0 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
1bcf0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
1bd00 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
1bd10 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
1bd20 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
1bd30 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1bd40 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1bd50 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1bd60 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
1bd70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
1bd80 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
1bd90 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
1bda0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
1bdb0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
1bdc0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
1bdd0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1bde0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1bdf0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
1be00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1be10 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20  F: Set the Last 
1be20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c  Insert Rowid val
1be30 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ue..** METHOD: s
1be40 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
1be50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73   sqlite3_set_las
1be60 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1be70 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f  , R) method allo
1be80 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ws the applicati
1be90 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65  on to.** set the
1bea0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1beb0 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  by calling sqlit
1bec0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1bed0 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a  owid(D) to R .**
1bee0 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69   without inserti
1bef0 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68  ng a row into th
1bf00 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 53  e database..*/.S
1bf10 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1bf20 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1bf30 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
1bf40 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  ite3*,sqlite3_in
1bf50 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
1bf60 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
1bf70 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1bf80 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1bf90 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1bfa0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1bfb0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1bfc0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1bfd0 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
1bfe0 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1bff0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
1c000 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
1c010 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1c020 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
1c030 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
1c040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
1c050 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
1c060 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
1c070 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
1c080 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
1c090 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
1c0a0 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
1c0b0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1c0c0 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
1c0d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
1c0e0 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
1c0f0 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
1c100 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1c110 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1c120 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
1c130 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
1c140 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
1c150 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
1c160 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
1c170 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1c180 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
1c190 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
1c1a0 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
1c1b0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
1c1c0 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
1c1d0 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1c1e0 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
1c1f0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
1c200 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
1c210 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
1c220 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
1c230 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
1c240 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
1c250 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
1c260 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
1c270 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1c280 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
1c290 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
1c2a0 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
1c2b0 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
1c2c0 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
1c2d0 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
1c2e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
1c2f0 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
1c300 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
1c310 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1c320 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
1c330 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
1c340 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1c350 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
1c360 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
1c370 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
1c380 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
1c390 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
1c3a0 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
1c3b0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
1c3c0 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
1c3d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1c3e0 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
1c3f0 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
1c400 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
1c410 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
1c420 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1c430 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
1c440 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
1c450 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
1c460 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
1c470 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
1c480 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1c490 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
1c4a0 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
1c4b0 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
1c4c0 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
1c4d0 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
1c4e0 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
1c4f0 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
1c500 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
1c510 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
1c520 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
1c530 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1c540 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1c550 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1c560 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
1c570 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
1c580 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
1c590 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
1c5a0 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
1c5b0 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
1c5c0 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
1c5d0 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
1c5e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1c5f0 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
1c600 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
1c610 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
1c620 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
1c630 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
1c640 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
1c650 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
1c660 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
1c670 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
1c680 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
1c690 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
1c6a0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1c6b0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1c6c0 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1c6d0 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
1c6e0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
1c6f0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
1c700 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
1c710 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
1c720 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
1c730 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1c740 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
1c750 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
1c760 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
1c770 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
1c780 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
1c790 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
1c7a0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1c7b0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
1c7c0 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
1c7d0 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1c7e0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1c7f0 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
1c800 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  er..**.** If a s
1c810 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
1c820 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
1c830 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1c840 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1c850 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
1c860 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1c870 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1c880 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1c890 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1c8a0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1c8b0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ful..**.** See a
1c8c0 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  lso:.** <ul>.** 
1c8d0 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69 74 65  <li> the [sqlite
1c8e0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1c8f0 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
1c900 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f  <li> the [count_
1c910 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a  changes pragma].
1c920 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61  ** <li> the [cha
1c930 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1c940 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65  ion].** <li> the
1c950 20 5b 64 61 74 61 5f 76 65 72 73 69 6f 6e 20 70   [data_version p
1c960 72 61 67 6d 61 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ragma].** </ul>.
1c970 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1c980 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
1c990 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1c9a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
1c9b0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
1c9c0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
1c9d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c9e0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1c9f0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1ca00 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
1ca10 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
1ca20 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
1ca30 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
1ca40 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
1ca50 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
1ca60 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
1ca70 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
1ca80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ca90 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
1caa0 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
1cab0 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
1cac0 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
1cad0 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
1cae0 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
1caf0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1cb00 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
1cb10 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
1cb20 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1cb30 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1cb40 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
1cb50 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
1cb60 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
1cb70 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
1cb80 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
1cb90 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
1cba0 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
1cbb0 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
1cbc0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
1cbd0 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
1cbe0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1cbf0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1cc00 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
1cc10 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
1cc20 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1cc30 2a 2a 0a 2a 2a 20 54 68 69 73 20 74 68 65 20 5b  **.** This the [
1cc40 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1cc50 61 6e 67 65 73 28 44 29 5d 20 69 6e 74 65 72 66  anges(D)] interf
1cc60 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ace only reports
1cc70 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
1cc80 66 20 72 6f 77 73 20 74 68 61 74 20 63 68 61 6e  f rows that chan
1cc90 67 65 64 20 64 75 65 20 74 6f 20 53 51 4c 20 73  ged due to SQL s
1cca0 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 61 67 61  tatement run aga
1ccb0 69 6e 73 74 20 64 61 74 61 62 61 73 65 0a 2a 2a  inst database.**
1ccc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
1ccd0 41 6e 79 20 63 68 61 6e 67 65 73 20 62 79 20 6f  Any changes by o
1cce0 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f  ther database co
1ccf0 6e 6e 65 63 74 69 6f 6e 73 20 61 72 65 20 69 67  nnections are ig
1cd00 6e 6f 72 65 64 2e 0a 2a 2a 20 54 6f 20 64 65 74  nored..** To det
1cd10 65 63 74 20 63 68 61 6e 67 65 73 20 61 67 61 69  ect changes agai
1cd20 6e 73 74 20 61 20 64 61 74 61 62 61 73 65 20 66  nst a database f
1cd30 69 6c 65 20 66 72 6f 6d 20 6f 74 68 65 72 20 64  ile from other d
1cd40 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
1cd50 63 74 69 6f 6e 73 20 75 73 65 20 74 68 65 20 5b  ctions use the [
1cd60 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72 73  PRAGMA data_vers
1cd70 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 6f 72 20  ion] command or 
1cd80 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
1cd90 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f  CNTL_DATA_VERSIO
1cda0 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  N] [file control
1cdb0 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 61 20 73  ]..** .** If a s
1cdc0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
1cdd0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
1cde0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1cdf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1ce00 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
1ce10 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1ce20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1ce30 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1ce40 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
1ce50 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
1ce60 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a  eaningful..**.**
1ce70 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75   See also:.** <u
1ce80 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  l>.** <li> the [
1ce90 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1cea0 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
1ceb0 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f  <li> the [count_
1cec0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a  changes pragma].
1ced0 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61  ** <li> the [cha
1cee0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1cef0 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65  ion].** <li> the
1cf00 20 5b 64 61 74 61 5f 76 65 72 73 69 6f 6e 20 70   [data_version p
1cf10 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74  ragma].** <li> t
1cf20 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
1cf30 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b  _DATA_VERSION] [
1cf40 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d 0a 2a 2a  file control].**
1cf50 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
1cf60 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1cf70 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1cf80 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1cf90 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1cfa0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1cfb0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1cfc0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1cfd0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1cfe0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1cff0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1d000 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1d010 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1d020 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1d030 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1d040 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1d050 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1d060 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1d070 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1d080 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1d090 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1d0a0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1d0b0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1d0c0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1d0d0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1d0e0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1d0f0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1d100 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1d110 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1d120 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1d130 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1d140 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1d150 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1d160 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1d170 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1d180 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1d190 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1d1a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d1b0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1d1c0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1d1d0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1d1e0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1d1f0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1d200 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1d210 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1d220 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1d230 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1d240 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1d250 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1d260 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1d270 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1d280 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1d290 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1d2a0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1d2b0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1d2c0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1d2d0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1d2e0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1d2f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1d300 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1d310 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1d320 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1d330 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1d340 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1d350 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1d360 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1d370 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1d380 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1d390 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1d3a0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1d3b0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1d3c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1d3d0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1d3e0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1d3f0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1d400 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1d410 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1d420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d430 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1d440 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1d450 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1d460 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1d470 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1d480 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1d490 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1d4a0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1d4b0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1d4c0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1d4d0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1d4e0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1d4f0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1d500 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1d510 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1d520 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1d530 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1d540 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1d550 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1d560 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1d570 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1d580 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1d590 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1d5a0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1d5b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1d5c0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1d5d0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1d5e0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1d5f0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1d600 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1d610 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1d620 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1d630 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1d640 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1d650 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1d660 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 53 51  l returns..*/.SQ
1d670 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1d680 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1d690 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1d6a0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1d6b0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1d6c0 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
1d6d0 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
1d6e0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
1d6f0 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
1d700 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
1d710 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
1d720 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
1d730 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
1d740 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
1d750 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1d760 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
1d770 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
1d780 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
1d790 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
1d7a0 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
1d7b0 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
1d7c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1d7d0 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
1d7e0 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
1d7f0 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
1d800 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1d810 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
1d820 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
1d830 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
1d840 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
1d850 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
1d860 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
1d870 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
1d880 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
1d890 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
1d8a0 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
1d8b0 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
1d8c0 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
1d8d0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
1d8e0 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
1d8f0 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
1d900 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
1d910 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
1d920 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
1d930 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
1d940 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
1d950 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
1d960 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
1d970 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
1d980 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
1d990 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
1d9a0 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
1d9b0 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
1d9c0 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
1d9d0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
1d9e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1d9f0 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
1da00 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
1da10 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
1da20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1da30 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
1da40 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
1da50 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1da60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
1da70 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
1da80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
1da90 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
1daa0 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
1dab0 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
1dac0 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
1dad0 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
1dae0 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
1daf0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
1db00 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
1db10 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
1db20 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
1db30 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
1db40 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1db50 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1db60 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1db70 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1db80 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
1db90 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
1dba0 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
1dbb0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1dbc0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
1dbd0 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
1dbe0 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
1dbf0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1dc00 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
1dc10 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
1dc20 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
1dc30 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1dc40 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
1dc50 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1dc60 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
1dc70 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
1dc80 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1dc90 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1dca0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1dcb0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1dcc0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1dcd0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1dce0 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
1dcf0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
1dd00 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
1dd10 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f  r *sql);.SQLITE_
1dd20 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1dd30 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1dd40 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1dd50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1dd60 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1dd70 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1dd80 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1dd90 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1dda0 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1ddb0 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1ddc0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1ddd0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1dde0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1ddf0 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1de00 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1de10 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1de20 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1de30 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1de40 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1de50 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1de60 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1de70 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1de80 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1de90 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1dea0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1deb0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1dec0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1ded0 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1dee0 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1def0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1df00 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1df10 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1df20 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1df30 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1df40 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1df50 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1df60 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1df70 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1df80 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1df90 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1dfa0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1dfb0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1dfc0 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1dfd0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1dfe0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1dff0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1e000 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1e010 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1e020 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1e030 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1e040 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1e050 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1e060 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1e070 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1e080 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1e090 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1e0a0 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1e0b0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1e0c0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1e0d0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1e0e0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1e0f0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1e100 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1e110 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1e120 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1e130 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1e140 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1e150 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1e160 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1e170 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1e180 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1e190 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1e1a0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1e1b0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1e1c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1e1d0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1e1e0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1e1f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e200 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1e210 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1e220 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1e230 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1e240 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1e250 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1e260 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1e270 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1e280 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1e290 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1e2a0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1e2b0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1e2c0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1e2d0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1e2e0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1e2f0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1e300 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1e310 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1e320 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1e330 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1e340 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1e350 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1e360 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1e370 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1e380 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1e390 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1e3a0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1e3b0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1e3c0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1e3d0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1e3e0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1e3f0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1e400 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1e410 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1e420 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1e430 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1e440 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1e450 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1e460 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1e470 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1e480 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1e490 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1e4a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1e4b0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1e4c0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1e4d0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1e4e0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1e4f0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1e500 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1e510 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1e520 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1e530 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1e540 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1e550 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1e560 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1e570 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1e580 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1e590 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1e5a0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1e5b0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1e5c0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1e5d0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1e5e0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1e5f0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1e600 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1e610 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1e620 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1e630 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1e640 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1e650 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1e660 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1e670 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1e680 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1e690 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1e6a0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1e6b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1e6c0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1e6d0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1e6e0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1e6f0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1e700 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1e710 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1e720 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1e730 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1e740 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1e750 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1e760 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1e770 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1e780 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1e790 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1e7a0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1e7b0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1e7c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1e7d0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1e7e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1e7f0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1e800 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1e810 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1e820 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1e830 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1e840 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1e850 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1e860 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1e870 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1e880 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1e890 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1e8a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e8b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1e8c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1e8d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1e8e0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1e8f0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1e900 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
1e910 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ),void*);../*.**
1e920 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1e930 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1e940 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1e950 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1e960 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1e970 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1e980 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1e990 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1e9a0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1e9b0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1e9c0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1e9d0 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1e9e0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1e9f0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1ea00 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1ea10 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1ea20 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1ea30 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1ea40 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1ea50 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1ea60 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1ea70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1ea80 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1ea90 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1eaa0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1eab0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1eac0 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1ead0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1eae0 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1eaf0 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1eb00 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1eb10 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1eb20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1eb30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1eb40 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1eb50 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1eb60 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1eb70 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1eb80 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1eb90 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1eba0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1ebb0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1ebc0 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1ebd0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1ebe0 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1ebf0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1ec00 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1ec10 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1ec20 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1ec30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1ec40 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1ec50 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54  imeout].*/.SQLIT
1ec60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1ec70 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1ec80 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1ec90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1eca0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1ecb0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1ecc0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1ecd0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1ece0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1ecf0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1ed00 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1ed10 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1ed20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1ed30 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1ed40 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1ed50 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1ed60 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1ed70 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1ed80 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1ed90 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1eda0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1edb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1edc0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1edd0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1ede0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1edf0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1ee00 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1ee10 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1ee20 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1ee30 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1ee40 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1ee50 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1ee60 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1ee70 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1ee80 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1ee90 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1eea0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1eeb0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1eec0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1eed0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1eee0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1eef0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1ef00 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1ef10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1ef20 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1ef30 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1ef40 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1ef50 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1ef60 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1ef70 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1ef80 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1ef90 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1efa0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1efb0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1efc0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1efd0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1efe0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1eff0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1f000 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1f010 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1f020 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1f030 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1f040 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1f050 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1f060 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1f070 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1f080 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1f090 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1f0a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1f0b0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1f0c0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1f0d0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1f0e0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1f0f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1f100 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1f110 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1f120 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1f130 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1f140 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1f150 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1f160 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1f170 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1f180 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1f190 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1f1a0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1f1b0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1f1c0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1f1d0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1f1e0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1f1f0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1f200 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1f210 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1f220 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1f230 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1f240 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1f250 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1f260 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1f270 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1f280 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1f290 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1f2a0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1f2b0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1f2c0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1f2d0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1f2e0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1f2f0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1f300 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1f310 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1f320 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1f330 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1f340 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1f350 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1f360 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1f370 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1f380 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1f390 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1f3a0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1f3b0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1f3c0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1f3d0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1f3e0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1f3f0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1f400 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1f410 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1f420 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1f430 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1f440 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1f450 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1f460 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1f470 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1f480 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1f490 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1f4a0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1f4b0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1f4c0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1f4d0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1f4e0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1f4f0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1f500 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1f510 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1f520 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1f530 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1f540 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1f550 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1f560 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1f570 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1f580 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1f590 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1f5a0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1f5b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1f5c0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1f5d0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1f5e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1f5f0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1f600 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1f610 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1f620 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1f630 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1f640 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1f650 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1f660 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1f670 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1f680 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1f690 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1f6a0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1f6b0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1f6c0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1f6d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1f6e0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1f6f0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1f700 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1f710 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1f720 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1f730 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1f740 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1f750 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1f760 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1f770 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1f780 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1f790 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1f7a0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1f7b0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1f7c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1f7d0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1f7e0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1f7f0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1f800 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1f810 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1f820 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1f830 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1f840 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1f850 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1f860 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1f870 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1f880 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1f890 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1f8a0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1f8b0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1f8c0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1f8d0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1f8e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1f8f0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1f900 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f910 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1f920 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
1f930 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1f940 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1f950 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1f960 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1f970 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1f980 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1f990 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1f9a0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1f9b0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1f9c0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1f9d0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1f9e0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1f9f0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1fa00 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1fa10 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1fa20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1fa30 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1fa40 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1fa50 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1fa60 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1fa70 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1fa80 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
1fa90 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1faa0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1fab0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1fac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1fad0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1fae0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1faf0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1fb00 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1fb10 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1fb20 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1fb30 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1fb40 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1fb50 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1fb60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1fb70 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20  understand most 
1fb80 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f  of the common fo
1fb90 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1fba0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1fbb0 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 70 72  ndard library pr
1fbc0 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20  intf() .** plus 
1fbd0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1fbe0 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72  non-standard for
1fbf0 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d  mats ([%q], [%Q]
1fc00 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d  , [%w], and [%z]
1fc10 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 62  )..** See the [b
1fc20 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29  uilt-in printf()
1fc30 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
1fc40 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a  for details..**.
1fc50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1fc60 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1fc70 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1fc80 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1fc90 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1fca0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1fcb0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1fcc0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e  te3_malloc64()].
1fcd0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1fce0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1fcf0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1fd00 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1fd10 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1fd20 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1fd30 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1fd40 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1fd50 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1fd60 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 75 6e  alloc64()] is un
1fd70 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1fd80 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1fd90 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1fda0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1fdb0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1fdc0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1fdd0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1fde0 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1fdf0 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1fe00 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1fe10 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1fe20 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1fe30 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1fe40 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1fe50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1fe60 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1fe70 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1fe80 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1fe90 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1fea0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1feb0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1fec0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1fed0 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1fee0 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1fef0 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1ff00 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1ff10 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1ff20 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1ff30 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1ff40 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1ff50 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1ff60 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1ff70 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1ff80 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1ff90 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1ffa0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1ffb0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1ffc0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1ffd0 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1ffe0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1fff0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
20000 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
20010 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
20020 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
20030 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
20040 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
20050 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
20060 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
20070 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
20080 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
20090 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
200a0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
200b0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
200c0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
200d0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
200e0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
200f0 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
20100 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
20110 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
20120 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
20130 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
20140 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
20150 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
20160 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
20170 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
20180 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
20190 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
201a0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
201b0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
201c0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
201d0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
201e0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
201f0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
20200 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
20210 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
20220 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ntf()..**.** See
20230 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69   also:  [built-i
20240 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72  n printf()], [pr
20250 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e 63 74  intf() SQL funct
20260 69 6f 6e 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion].*/.SQLITE_A
20270 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
20280 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
20290 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54  har*,...);.SQLIT
202a0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
202b0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
202c0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
202d0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
202e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
202f0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
20300 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
20310 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
20320 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
20330 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
20340 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
20350 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
20360 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
20370 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
20380 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
20390 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
203a0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
203b0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
203c0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
203d0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
203e0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
203f0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
20400 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
20410 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
20420 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
20430 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
20440 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
20450 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
20460 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
20470 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
20480 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
20490 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
204a0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
204b0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
204c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
204d0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
204e0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
204f0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
20500 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
20510 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
20520 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
20530 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
20540 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
20550 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
20560 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
20570 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
20580 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
20590 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
205a0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
205b0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
205c0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
205d0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
205e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
205f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20600 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
20610 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
20620 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
20630 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
20640 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
20650 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
20660 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
20670 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
20680 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
20690 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
206a0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
206b0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
206c0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
206d0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
206e0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
206f0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
20700 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
20710 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
20720 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
20730 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
20740 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
20750 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
20760 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
20770 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
20780 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
20790 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
207a0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
207b0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
207c0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
207d0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
207e0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
207f0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
20800 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
20810 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
20820 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
20830 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
20840 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
20850 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
20860 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
20870 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
20880 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
20890 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
208a0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
208b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
208c0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
208d0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
208e0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
208f0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
20900 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20910 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
20920 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
20930 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
20940 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
20950 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
20960 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
20970 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20980 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
20990 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
209a0 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
209b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
209c0 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
209d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
209e0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
209f0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
20a00 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
20a10 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
20a20 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
20a30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
20a40 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
20a50 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
20a60 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
20a70 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
20a80 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
20a90 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
20aa0 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
20ab0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
20ac0 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
20ad0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
20ae0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
20af0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
20b00 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
20b10 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
20b20 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
20b30 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
20b40 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
20b50 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
20b60 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
20b70 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
20b80 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
20b90 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
20ba0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
20bb0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
20bc0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
20bd0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
20be0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
20bf0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
20c00 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
20c10 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
20c20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
20c30 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
20c40 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
20c50 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
20c60 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
20c70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
20c80 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
20c90 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
20ca0 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
20cb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
20cc0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
20cd0 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
20ce0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
20cf0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
20d00 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
20d10 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
20d20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
20d30 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
20d40 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
20d50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20d60 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
20d70 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
20d80 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
20d90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
20da0 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
20db0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
20dc0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
20dd0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
20de0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
20df0 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
20e00 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
20e10 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
20e20 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
20e30 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
20e40 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
20e50 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
20e60 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
20e70 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
20e80 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
20e90 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
20ea0 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
20eb0 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
20ec0 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
20ed0 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
20ee0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
20ef0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
20f00 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
20f10 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
20f20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
20f30 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
20f40 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
20f50 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
20f60 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
20f70 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
20f80 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
20f90 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
20fa0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
20fb0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
20fc0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
20fd0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
20fe0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
20ff0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
21000 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
21010 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
21020 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
21030 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
21040 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
21050 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
21060 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
21070 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
21080 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
21090 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
210a0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
210b0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
210c0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
210d0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
210e0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
210f0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
21100 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
21110 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
21120 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
21130 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
21140 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
21150 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
21160 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
21170 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
21180 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
21190 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
211a0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
211b0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
211c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
211d0 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
211e0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
211f0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
21200 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
21210 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
21220 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
21230 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
21240 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
21250 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
21260 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
21270 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
21280 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
21290 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
212a0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
212b0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
212c0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
212d0 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
212e0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
212f0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
21300 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
21310 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
21320 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
21330 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
21340 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
21350 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
21360 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
21370 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
21380 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
21390 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
213a0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
213b0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
213c0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
213d0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
213e0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
213f0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
21400 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
21410 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
21420 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
21430 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
21440 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
21450 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
21460 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
21470 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
21480 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
21490 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
214a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
214b0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
214c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
214d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
214e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
214f0 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  oc(int);.SQLITE_
21500 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
21510 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74  3_malloc64(sqlit
21520 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49  e3_uint64);.SQLI
21530 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
21540 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
21550 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
21560 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
21570 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69  e3_realloc64(voi
21580 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
21590 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
215a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
215b0 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  e(void*);.SQLITE
215c0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e  _API sqlite3_uin
215d0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
215e0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
215f0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
21600 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
21610 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
21620 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
21630 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
21640 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
21650 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
21660 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
21670 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
21680 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
21690 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
216a0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
216b0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
216c0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
216d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
216e0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
216f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
21700 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
21710 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
21720 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
21730 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
21740 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
21750 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
21760 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
21770 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
21780 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
21790 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
217a0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
217b0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
217c0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
217d0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
217e0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
217f0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
21800 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
21810 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
21820 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
21830 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
21840 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
21850 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
21860 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
21870 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
21880 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
21890 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
218a0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
218b0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
218c0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
218d0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
218e0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
218f0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
21900 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
21910 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
21920 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
21930 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
21940 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
21950 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
21960 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
21970 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
21980 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
21990 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
219a0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
219b0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
219c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
219d0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
219e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
219f0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
21a00 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
21a10 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
21a20 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
21a30 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
21a40 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
21a50 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
21a60 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
21a70 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
21a80 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
21a90 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
21aa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
21ab0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
21ac0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
21ad0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
21ae0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
21af0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
21b00 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
21b10 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
21b20 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
21b30 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
21b40 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
21b50 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
21b60 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
21b70 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
21b80 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
21b90 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
21ba0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
21bb0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
21bc0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
21bd0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
21be0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
21bf0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
21c00 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
21c10 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
21c20 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
21c30 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
21c40 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
21c50 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
21c60 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
21c70 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
21c80 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
21c90 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
21ca0 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
21cb0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
21cc0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
21cd0 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
21ce0 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
21cf0 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
21d00 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
21d10 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
21d20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
21d30 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
21d40 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
21d50 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
21d60 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
21d70 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
21d80 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
21d90 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
21da0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
21db0 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
21dc0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
21dd0 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
21de0 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
21df0 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
21e00 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
21e10 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
21e20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
21e30 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
21e40 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
21e50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
21e60 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
21e70 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49   method..*/.SQLI
21e80 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
21e90 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
21ea0 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
21eb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21ec0 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
21ed0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
21ee0 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
21ef0 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57   sqlite3.** KEYW
21f00 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65  ORDS: {authorize
21f10 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a  r callback}.**.*
21f20 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
21f30 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
21f40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21f50 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
21f60 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
21f70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
21f80 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
21f90 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
21fa0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
21fb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
21fc0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
21fd0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
21fe0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
21ff0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
22000 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
22010 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
22020 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
22030 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22040 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  3()], [sqlite3_p
22050 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71  repare16()], [sq
22060 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22070 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  v2()],.** and [s
22080 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22090 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v3()].  ^At var
220a0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
220b0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
220c0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
220d0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
220e0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
220f0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
22100 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
22110 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22120 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
22130 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
22140 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
22150 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
22160 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
22170 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
22180 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
22190 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
221a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
221b0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
221c0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
221d0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
221e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
221f0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
22200 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
22210 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
22220 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
22230 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
22240 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
22250 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
22260 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
22270 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
22280 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
22290 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
222a0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
222b0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
222c0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
222d0 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
222e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
222f0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
22300 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
22310 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
22320 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
22330 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
22340 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
22350 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
22360 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
22370 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
22380 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
22390 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
223a0 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
223b0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
223c0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
223d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
223e0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
223f0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
22400 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
22410 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
22420 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
22430 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
22440 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
22450 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
22460 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
22470 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
22480 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22490 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
224a0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
224b0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
224c0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
224d0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
224e0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
224f0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
22500 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
22510 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
22520 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
22530 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
22540 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
22550 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
22560 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
22570 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
22580 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
22590 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
225a0 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65  e callback are e
225b0 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74  ither NULL point
225c0 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d  ers or zero-term
225d0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a  inated strings.*
225e0 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  * that contain a
225f0 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c  dditional detail
22600 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
22610 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
22620 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  zed..** Applicat
22630 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73  ions must always
22640 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20   be prepared to 
22650 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c  encounter a NULL
22660 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a   pointer in any.
22670 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  ** of the third 
22680 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74  through the sixt
22690 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  h parameters of 
226a0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
226b0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
226c0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
226d0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
226e0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
226f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
22700 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
22710 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
22720 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22730 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
22740 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
22750 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
22760 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
22770 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
22780 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
22790 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
227a0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
227b0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
227c0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
227d0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
227e0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
227f0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
22800 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
22810 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
22820 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
22830 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e   table..** ^When
22840 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65   a table is refe
22850 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c  renced by a [SEL
22860 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75  ECT] but no colu
22870 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a  mn values are.**
22880 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20   extracted from 
22890 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20  that table (for 
228a0 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65  example in a que
228b0 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45  ry like.** "SELE
228c0 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d  CT count(*) FROM
228d0 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20   tab") then the 
228e0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75  [SQLITE_READ] au
228f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22900 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20  k.** is invoked 
22910 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61  once for that ta
22920 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d  ble with a colum
22930 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61  n name that is a
22940 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
22950 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
22960 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
22970 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
22980 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
22990 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
229a0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
229b0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
229c0 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
229d0 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
229e0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
229f0 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
22a00 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
22a10 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
22a20 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
22a30 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
22a40 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
22a50 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
22a60 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
22a70 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
22a80 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
22a90 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
22aa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
22ab0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
22ac0 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
22ad0 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
22ae0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
22af0 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
22b00 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
22b10 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
22b20 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
22b30 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
22b40 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
22b50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
22b60 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
22b70 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
22b80 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
22b90 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
22ba0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
22bb0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
22bc0 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
22bd0 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
22be0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
22bf0 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
22c00 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
22c10 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
22c20 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
22c30 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
22c40 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
22c50 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
22c60 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
22c70 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
22c80 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
22c90 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
22ca0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
22cb0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
22cc0 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
22cd0 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
22ce0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
22cf0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
22d00 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
22d10 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
22d20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
22d30 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
22d40 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
22d50 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
22d60 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
22d70 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
22d80 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
22d90 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
22da0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
22db0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
22dc0 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
22dd0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
22de0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
22df0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
22e00 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
22e10 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
22e20 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
22e30 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
22e40 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
22e50 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
22e60 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
22e70 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
22e80 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
22e90 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
22ea0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
22eb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
22ec0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22ed0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
22ee0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
22ef0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
22f00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22f10 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
22f20 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22f30 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
22f40 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
22f50 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
22f60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22f70 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
22f80 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
22f90 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
22fa0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
22fb0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
22fc0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
22fd0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
22fe0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
22ff0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
23000 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
23010 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
23020 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
23030 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
23040 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
23050 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
23060 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
23070 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
23080 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
23090 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
230a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
230b0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
230c0 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
230d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
230e0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
230f0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
23100 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
23110 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
23120 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
23130 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
23140 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
23150 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
23160 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
23170 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
23180 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
23190 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
231a0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
231b0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
231c0 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
231d0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
231e0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
231f0 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
23200 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
23210 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
23220 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53  ema change..*/.S
23230 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
23240 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23250 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
23260 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
23270 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
23280 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
23290 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
232a0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
232b0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
232c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
232d0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
232e0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
232f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
23300 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
23310 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
23320 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
23330 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
23340 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
23350 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
23360 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
23370 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
23380 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
23390 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
233a0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
233b0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
233c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
233d0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
233e0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
233f0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
23400 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
23410 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
23420 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
23430 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
23440 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
23450 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
23460 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
23470 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
23480 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
23490 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
234a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
234b0 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
234c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
234d0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
234e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
234f0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
23500 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
23510 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
23520 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
23530 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
23540 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
23550 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
23560 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
23570 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
23580 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
23590 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
235a0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
235b0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
235c0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
235d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
235e0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
235f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
23600 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
23610 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
23620 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
23630 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
23640 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
23650 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
23660 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
23670 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
23680 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
23690 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
236a0 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
236b0 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
236c0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
236d0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
236e0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
236f0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
23700 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
23710 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
23720 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
23730 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
23740 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
23750 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
23760 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
23770 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
23780 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
23790 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
237a0 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
237b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
237c0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
237d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
237e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
237f0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
23800 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
23810 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
23820 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
23830 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
23840 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
23850 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
23860 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
23870 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
23880 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
23890 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
238a0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
238b0 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
238c0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
238d0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
238e0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
238f0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
23900 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23910 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23920 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
23930 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
23940 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
23950 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
23960 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
23970 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
23980 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
23990 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
239a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
239b0 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
239c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
239d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
239e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
239f0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
23a00 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
23a10 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
23a20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23a30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23a40 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
23a50 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
23a60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23a70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23a80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23a90 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
23aa0 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
23ab0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
23ac0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
23ad0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23ae0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
23af0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
23b00 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
23b10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23b20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23b30 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
23b40 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
23b50 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
23b60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
23b70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
23b80 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
23b90 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
23ba0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
23bb0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23bc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
23bd0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
23be0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
23bf0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
23c00 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23c10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23c20 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
23c30 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
23c40 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
23c50 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
23c60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23c70 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
23c80 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
23c90 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
23ca0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23cb0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23cc0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
23cd0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
23ce0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
23cf0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23d00 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
23d10 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
23d20 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
23d30 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
23d40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23d50 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
23d60 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
23d70 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
23d80 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
23d90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23da0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
23db0 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
23dc0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
23dd0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23de0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23df0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
23e00 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
23e10 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
23e20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23e30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23e40 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
23e50 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
23e60 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
23e70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23e80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23e90 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
23ea0 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
23eb0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
23ec0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23ed0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23ee0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
23ef0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
23f00 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
23f10 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
23f20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23f30 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
23f40 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
23f50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23f60 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
23f70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23f80 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
23f90 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
23fa0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
23fb0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23fc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23fd0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
23fe0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
23ff0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
24000 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24020 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
24030 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
24040 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
24050 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
24060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
24070 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
24080 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
24090 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
240a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
240b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
240c0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
240d0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
240e0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
240f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24100 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
24110 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
24120 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
24130 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
24140 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
24150 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
24160 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
24170 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
24180 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
24190 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
241a0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
241b0 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
241c0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
241d0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
241e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
241f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
24200 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
24210 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
24220 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
24230 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
24240 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
24250 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
24260 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24270 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
24280 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
24290 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
242a0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
242b0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
242c0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
242d0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
242e0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
242f0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
24300 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
24310 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
24320 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
24330 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
24340 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
24350 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
24360 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
24370 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
24380 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
24390 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
243a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
243b0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
243c0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
243d0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
243e0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
243f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
24400 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
24410 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65   deprecated. Use
24420 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
24430 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  ace_v2()] interf
24440 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f  ace.** instead o
24450 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64  f the routines d
24460 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a  escribed here..*
24470 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24480 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
24490 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
244a0 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
244b0 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
244c0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
244d0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
244e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
244f0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
24500 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
24510 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
24520 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
24530 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
24540 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
24550 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
24560 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
24570 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
24580 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24590 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
245a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
245b0 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
245c0 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
245d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
245e0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
245f0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
24600 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
24610 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
24620 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
24630 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
24640 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
24650 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
24660 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
24670 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
24680 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
24690 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
246a0 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
246b0 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
246c0 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
246d0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
246e0 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
246f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
24700 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
24710 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
24720 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
24730 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
24740 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
24750 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
24770 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
24780 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
24790 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
247a0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
247b0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
247c0 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
247d0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
247e0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
247f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
24800 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
24810 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
24820 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
24830 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
24840 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
24850 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
24860 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
24870 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
24880 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
24890 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
248a0 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
248b0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
248c0 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
248d0 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
248e0 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
248f0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
24900 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
24910 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
24920 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
24930 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
24940 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
24950 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
24960 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
24970 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
24980 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
24990 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
249a0 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
249b0 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
249c0 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
249d0 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
249e0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
249f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
24a00 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
24a10 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a  EPRECATED void *
24a20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
24a30 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
24a40 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
24a50 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
24a60 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
24a70 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
24a80 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
24a90 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
24aa0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
24ab0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
24ac0 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
24ad0 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
24ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24af0 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74   SQL Trace Event
24b00 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
24b10 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45  DS: SQLITE_TRACE
24b20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
24b30 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20  stants identify 
24b40 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74  classes of event
24b50 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f  s that can be mo
24b60 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67  nitored.** using
24b70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
24b80 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e  ace_v2()] tracin
24b90 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20  g logic.  The M 
24ba0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
24bb0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
24bc0 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e  (D,M,X,P)] is an
24bd0 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
24be0 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  on of one or mor
24bf0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
24c00 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
24c10 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67    ^The first arg
24c20 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
24c30 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ce callback.** i
24c40 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
24c50 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
24c60 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63  ..**.** New trac
24c70 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ing constants ma
24c80 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
24c90 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
24ca0 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61  *.** ^A trace ca
24cb0 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20  llback has four 
24cc0 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c  arguments: xCall
24cd0 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
24ce0 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
24cf0 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
24d00 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64  integer type cod
24d10 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68  es above..** ^Th
24d20 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
24d30 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
24d40 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61  ntext pointer pa
24d50 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
24d60 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
24d70 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
24d80 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ace_v2()]..** Th
24d90 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
24da0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
24db0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
24dc0 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
24dd0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
24de0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d  ITE_TRACE_STMT]]
24df0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
24e00 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_STMT</dt>.** <
24e10 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
24e20 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63  ACE_STMT callbac
24e30 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
24e40 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  n a prepared sta
24e50 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20  tement.** first 
24e60 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61  begins running a
24e70 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f  nd possibly at o
24e80 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e  ther times durin
24e90 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69  g the.** executi
24ea0 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  on of the prepar
24eb0 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75  ed statement, su
24ec0 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61  ch as at the sta
24ed0 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72  rt of each.** tr
24ee0 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
24ef0 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  . ^The P argumen
24f00 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
24f10 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  o the.** [prepar
24f20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
24f30 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  The X argument i
24f40 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
24f50 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a   string which.**
24f60 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64   is the unexpand
24f70 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74  ed SQL text of t
24f80 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
24f90 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20  ement or an SQL 
24fa0 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74  comment .** that
24fb0 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69   indicates the i
24fc0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74  nvocation of a t
24fd0 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61  rigger.  ^The ca
24fe0 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75  llback can compu
24ff0 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  te.** the same t
25000 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68  ext that would h
25010 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65  ave been returne
25020 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20  d by the legacy 
25030 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
25040 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62  ].** interface b
25050 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72  y using the X ar
25060 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65  gument when X be
25070 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61  gins with "--" a
25080 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b  nd invoking.** [
25090 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
250a0 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69  _sql(P)] otherwi
250b0 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  se..**.** [[SQLI
250c0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
250d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
250e0 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e  ACE_PROFILE</dt>
250f0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
25100 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
25110 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64   callback provid
25120 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  es approximately
25130 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66   the same.** inf
25140 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70  ormation as is p
25150 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b  rovided by the [
25160 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
25170 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  )] callback..** 
25180 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
25190 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
251a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
251b0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
251c0 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70  .** X argument p
251d0 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69  oints to a 64-bi
251e0 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  t integer which 
251f0 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64  is the estimated
25200 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   of.** the numbe
25210 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20  r of nanosecond 
25220 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
25230 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  d statement took
25240 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65   to run..** ^The
25250 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
25260 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69  OFILE callback i
25270 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
25280 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  he statement fin
25290 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ishes..**.** [[S
252a0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d  QLITE_TRACE_ROW]
252b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
252c0 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  CE_ROW</dt>.** <
252d0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
252e0 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b  ACE_ROW callback
252f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
25300 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a  ever a prepared.
25310 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e  ** statement gen
25320 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20  erates a single 
25330 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20  row of result.  
25340 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
25350 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
25360 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
25370 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
25380 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65   the.** X argume
25390 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
253a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
253b0 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53  CE_CLOSE]] <dt>S
253c0 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
253d0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
253e0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  n SQLITE_TRACE_C
253f0 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  LOSE callback is
25400 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
25410 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
25420 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
25430 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
25440 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
25450 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
25460 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65  connection] obje
25470 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20  ct.** and the X 
25480 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
25490 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ed..** </dl>.*/.
254a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
254b0 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20  RACE_STMT       
254c0 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
254d0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
254e0 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e  E    0x02.#defin
254f0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  e SQLITE_TRACE_R
25500 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23  OW        0x04.#
25510 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
25520 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30  ACE_CLOSE      0
25530 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x08../*.** CAPI3
25540 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48  REF: SQL Trace H
25550 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ook.** METHOD: s
25560 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
25570 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  e sqlite3_trace_
25580 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65  v2(D,M,X,P) inte
25590 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
255a0 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  a trace callback
255b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61  .** function X a
255c0 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65  gainst [database
255d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
255e0 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d  using property m
255f0 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e  ask M.** and con
25600 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20  text pointer P. 
25610 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62   ^If the X callb
25620 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f  ack is.** NULL o
25630 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20  r if the M mask 
25640 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72  is zero, then tr
25650 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  acing is disable
25660 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67  d.  The.** M arg
25670 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
25680 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65  the bitwise OR-e
25690 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
256a0 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  .** zero or more
256b0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20   [SQLITE_TRACE] 
256c0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
256d0 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65   ^Each call to e
256e0 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72  ither sqlite3_tr
256f0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
25700 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72  _trace_v2() over
25710 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65  rides .** (cance
25720 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61  ls) any prior ca
25730 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74  lls to sqlite3_t
25740 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
25750 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a  3_trace_v2()..**
25760 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62  .** ^The X callb
25770 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
25780 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74  henever any of t
25790 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69  he events identi
257a0 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b  fied by .** mask
257b0 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20   M occur.  ^The 
257c0 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76  integer return v
257d0 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61  alue from the ca
257e0 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e  llback is curren
257f0 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20  tly.** ignored, 
25800 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20  though this may 
25810 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
25820 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c   releases.  Call
25830 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  back.** implemen
25840 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72  tations should r
25850 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e  eturn zero to en
25860 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70  sure future comp
25870 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
25880 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
25890 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
258a0 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  th four argument
258b0 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  s: callback(T,C,
258c0 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
258d0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
258e0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
258f0 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e  RACE].** constan
25900 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77  ts to indicate w
25910 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  hy the callback 
25920 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20  was invoked..** 
25930 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
25940 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
25950 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
25960 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
25970 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
25980 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
25990 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
259a0 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71   T..**.** The sq
259b0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
259c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
259d0 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63  tended to replac
259e0 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  e the legacy.** 
259f0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
25a00 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64  te3_trace()] and
25a10 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
25a20 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68  e()], both of wh
25a30 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65  ich.** are depre
25a40 63 61 74 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  cated..*/.SQLITE
25a50 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
25a60 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
25a70 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
25a80 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a  d uMask,.  int(*
25a90 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
25aa0 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
25ab0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
25ac0 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
25ad0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
25ae0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
25af0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
25b00 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
25b10 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
25b20 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
25b30 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
25b40 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
25b50 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
25b60 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
25b70 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
25b80 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
25b90 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
25ba0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
25bb0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
25bc0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
25bd0 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
25be0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25bf0 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
25c00 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
25c10 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
25c20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
25c30 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
25c40 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
25c50 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
25c60 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
25c70 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
25c80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
25c90 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
25ca0 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
25cb0 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
25cc0 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
25cd0 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
25ce0 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
25cf0 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
25d00 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
25d10 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
25d20 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
25d30 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
25d40 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
25d50 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
25d60 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
25d70 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
25d80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
25d90 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
25da0 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
25db0 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
25dc0 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
25dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25de0 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
25df0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
25e00 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
25e10 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
25e20 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
25e30 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
25e40 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
25e50 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
25e60 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
25e70 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
25e80 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
25e90 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
25ea0 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
25eb0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
25ec0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
25ed0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
25ee0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
25ef0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
25f00 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
25f10 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
25f20 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
25f30 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
25f40 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
25f50 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
25f60 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
25f70 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
25f80 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
25f90 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
25fa0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
25fb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
25fc0 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
25fd0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
25fe0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
25ff0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26000 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
26010 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
26020 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
26030 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
26040 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
26050 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
26060 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
26070 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  **.*/.SQLITE_API
26080 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72   void sqlite3_pr
26090 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
260a0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
260b0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
260c0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
260d0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
260e0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
260f0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54  nection.** CONST
26100 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
26110 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
26120 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
26130 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
26140 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
26150 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
26160 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
26170 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
26180 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
26190 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
261a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
261b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
261c0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
261d0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
261e0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
261f0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
26200 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
26210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26220 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
26230 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
26240 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
26250 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
26260 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
26270 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
26280 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
26290 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
262a0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
262b0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
262c0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
262d0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
262e0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
262f0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
26300 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
26310 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
26320 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
26330 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
26340 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
26350 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
26360 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
26370 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
26380 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
26390 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
263a0 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
263b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
263c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
263d0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
263e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
263f0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
26400 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
26410 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
26420 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
26430 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
26440 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
26450 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
26460 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
26470 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
26480 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
26490 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
264a0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
264b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
264c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
264d0 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
264e0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
264f0 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
26500 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
26510 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
26520 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
26530 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
26540 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
26550 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
26560 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
26570 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
26580 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
26590 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
265a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
265b0 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
265c0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
265d0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
265e0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
265f0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
26600 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
26610 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
26620 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
26630 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
26640 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
26650 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
26660 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
26670 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
26680 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
26690 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
266a0 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
266b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
266c0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
266d0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
266e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
266f0 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
26700 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
26710 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
26720 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
26730 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
26740 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
26750 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
26760 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
26770 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
26780 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
26790 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
267a0 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
267b0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
267c0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
267d0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
267e0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
267f0 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
26800 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
26810 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
26820 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
26830 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
26840 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
26850 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
26860 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
26870 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
26880 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
26890 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
268a0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
268b0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
268c0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
268d0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
268e0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
268f0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
26900 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
26910 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
26920 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
26930 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
26940 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
26950 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
26960 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
26970 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
26980 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
26990 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
269a0 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
269b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
269c0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
269d0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
269e0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
269f0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
26a00 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
26a10 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
26a20 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
26a30 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
26a40 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
26a50 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
26a60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
26a70 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
26a80 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
26a90 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
26aa0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
26ab0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
26ac0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
26ad0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
26ae0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
26af0 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
26b00 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
26b10 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
26b20 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
26b30 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
26b40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
26b50 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
26b60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
26b70 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
26b80 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
26b90 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
26ba0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26bb0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
26bc0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
26bd0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
26be0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
26bf0 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
26c00 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
26c10 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
26c20 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
26c30 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
26c40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
26c50 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
26c60 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
26c70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26c80 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
26c90 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
26ca0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
26cb0 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
26cc0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
26cd0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
26ce0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
26cf0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
26d00 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
26d10 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
26d20 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
26d30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26d40 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
26d50 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
26d60 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
26d70 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
26d80 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
26d90 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
26da0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
26db0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
26dc0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
26dd0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
26de0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
26df0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
26e00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
26e10 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
26e20 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
26e30 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
26e40 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
26e50 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
26e60 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
26e70 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26e80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
26e90 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
26ea0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
26eb0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
26ec0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
26ed0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
26ee0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
26ef0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
26f00 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
26f10 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
26f20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
26f30 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
26f40 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
26f50 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
26f60 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
26f70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
26f80 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
26f90 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
26fa0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
26fb0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
26fc0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
26fd0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
26fe0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
26ff0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
27000 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
27010 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
27020 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
27030 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
27040 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
27050 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
27060 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
27070 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
27080 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
27090 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
270a0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
270b0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
270c0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
270d0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
270e0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
270f0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
27100 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
27110 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
27120 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
27130 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
27140 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
27150 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
27160 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
27170 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
27180 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
27190 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
271a0 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
271b0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
271c0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
271d0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
271e0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
271f0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
27200 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
27210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
27220 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
27230 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
27240 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
27250 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
27260 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
27270 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
27280 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
27290 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
272a0 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
272b0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
272c0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
272d0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
272e0 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
272f0 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
27300 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
27310 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
27320 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
27330 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
27340 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
27350 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72 67  in the third arg
27360 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
27370 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
27380 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
27390 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
273a0 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
273b0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
273c0 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
273d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
273e0 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
273f0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
27400 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
27410 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
27420 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
27430 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
27440 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
27450 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
27460 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
27470 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
27480 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
27490 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
274a0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
274b0 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
274c0 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
274d0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
274e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
274f0 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
27500 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
27510 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
27520 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
27530 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
27540 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
27550 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
27560 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
27570 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
27580 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
27590 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
275a0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
275b0 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
275c0 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
275d0 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
275e0 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
275f0 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
27600 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
27610 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
27620 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
27630 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
27640 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
27650 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
27660 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
27670 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
27680 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
27690 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
276a0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
276b0 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
276c0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
276d0 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
276e0 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
276f0 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
27700 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
27710 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
27720 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
27730 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
27740 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
27750 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
27760 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
27770 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
27780 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
27790 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
277a0 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
277b0 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
277c0 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
277d0 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
277e0 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
277f0 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
27800 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27810 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
27820 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
27830 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
27840 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
27850 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
27860 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
27870 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
27880 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
27890 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
278a0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
278b0 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
278c0 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
278d0 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
278e0 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
278f0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
27900 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
27910 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
27920 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
27930 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
27940 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
27950 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
27960 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
27970 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
27980 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
27990 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
279a0 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
279b0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
279c0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
279d0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
279e0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
279f0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
27a00 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
27a10 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
27a20 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
27a30 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
27a40 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
27a50 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
27a60 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
27a70 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
27a80 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
27a90 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
27aa0 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
27ab0 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
27ac0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
27ad0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
27ae0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
27af0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27b00 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
27b10 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
27b20 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
27b30 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
27b40 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
27b50 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
27b60 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
27b70 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
27b80 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
27b90 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
27ba0 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
27bb0 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
27bc0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
27bd0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
27be0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
27bf0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
27c00 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
27c10 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
27c20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
27c30 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
27c40 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
27c50 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
27c60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
27c70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27c80 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
27c90 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
27ca0 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
27cb0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
27cc0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
27cd0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
27ce0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
27cf0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
27d00 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
27d10 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
27d20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
27d30 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
27d40 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
27d50 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
27d60 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
27d70 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
27d80 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
27d90 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
27da0 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
27db0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
27dc0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
27dd0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
27de0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
27df0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
27e00 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
27e10 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
27e20 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
27e30 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
27e40 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
27e50 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
27e60 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
27e70 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
27e80 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
27e90 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
27ea0 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
27eb0 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
27ec0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
27ed0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
27ee0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
27ef0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
27f00 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
27f10 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
27f20 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
27f30 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
27f40 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
27f50 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
27f60 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
27f70 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
27f80 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
27f90 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
27fa0 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
27fb0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
27fc0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
27fd0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
27fe0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
27ff0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
28000 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
28010 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
28020 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
28030 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
28040 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
28050 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
28060 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
28070 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
28080 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
28090 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
280a0 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
280b0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
280c0 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
280d0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
280e0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
280f0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
28100 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
28110 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
28120 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
28130 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
28140 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
28150 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
28160 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
28170 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
28180 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
28190 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
281a0 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
281b0 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
281c0 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
281d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
281e0 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
281f0 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
28200 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
28210 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
28220 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
28230 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
28240 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
28250 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
28260 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
28270 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
28280 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
28290 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
282a0 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
282b0 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
282c0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
282d0 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
282e0 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
282f0 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
28300 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
28310 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
28320 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
28330 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
28340 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
28350 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
28360 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
28370 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
28380 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
28390 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
283a0 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
283b0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
283c0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
283d0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
283e0 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
283f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28400 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
28410 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
28420 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
28430 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
28440 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
28450 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
28460 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
28470 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
28480 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
28490 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
284a0 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
284b0 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
284c0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
284d0 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
284e0 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
284f0 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
28500 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
28510 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
28520 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
28530 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
28540 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
28550 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
28560 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
28570 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
28580 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
28590 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
285a0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
285b0 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
285c0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
285d0 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
285e0 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
285f0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
28600 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
28610 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
28620 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
28630 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
28640 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
28650 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
28660 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
28670 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
28680 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
28690 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
286a0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
286b0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
286c0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
286d0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
286e0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
286f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
28700 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
28710 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
28720 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
28730 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
28740 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
28750 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
28760 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
28770 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
28780 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
28790 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
287a0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
287b0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
287c0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
287d0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
287e0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
287f0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
28800 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
28810 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
28820 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
28830 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
28840 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
28850 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
28860 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
28870 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
28880 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
28890 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
288a0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
288b0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
288c0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
288d0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
288e0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
288f0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
28900 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
28910 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
28920 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
28930 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
28940 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
28950 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
28960 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
28970 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
28980 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
28990 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
289a0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
289b0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
289c0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
289d0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
289e0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
289f0 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
28a00 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
28a10 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
28a20 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
28a30 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
28a40 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
28a50 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
28a60 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
28a70 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
28a80 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
28a90 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
28aa0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
28ab0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
28ac0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
28ad0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
28ae0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
28af0 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
28b00 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
28b10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
28b20 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
28b30 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
28b40 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
28b50 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
28b60 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
28b70 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
28b80 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
28b90 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
28ba0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
28bb0 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
28bc0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
28bd0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
28be0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
28bf0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
28c00 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
28c10 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
28c20 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
28c30 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
28c40 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
28c50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
28c60 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
28c70 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
28c80 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
28c90 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
28ca0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
28cb0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
28cc0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
28cd0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
28ce0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
28cf0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
28d00 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
28d10 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
28d20 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
28d30 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
28d40 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
28d50 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
28d60 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
28d70 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
28d80 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
28d90 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
28da0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
28db0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
28dc0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
28dd0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
28de0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
28df0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
28e00 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
28e10 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
28e20 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
28e30 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
28e40 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
28e50 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
28e60 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
28e70 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
28e80 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
28e90 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
28ea0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
28eb0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
28ec0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
28ed0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
28ee0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
28ef0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
28f00 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
28f10 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
28f20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
28f30 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
28f40 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
28f50 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
28f60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
28f70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
28f80 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
28f90 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
28fa0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
28fb0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
28fc0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
28fd0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
28fe0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
28ff0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
29000 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
29010 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
29020 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
29030 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
29040 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
29050 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
29060 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
29070 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
29080 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
29090 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
290a0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
290b0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
290c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
290d0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
290e0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
290f0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
29100 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
29110 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
29120 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29130 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
29140 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51  directory].*/.SQ
29150 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
29160 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
29170 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
29180 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
29190 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
291a0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
291b0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
291c0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
291d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
291e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
291f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
29200 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
29210 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
29220 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
29230 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
29240 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
29250 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
29260 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
29270 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29280 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
29290 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
292a0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
292b0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
292c0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
292d0 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
292e0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
292f0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
29300 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
29310 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
29320 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
29330 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
29340 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
29350 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
29360 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
29370 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
29380 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
29390 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
293a0 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
293b0 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
293c0 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
293d0 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
293e0 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
293f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
29400 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
29410 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
29420 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
29430 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
29440 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
29450 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
29460 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
29470 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
29480 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
29490 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
294a0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
294b0 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
294c0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
294d0 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
294e0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
294f0 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
29500 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
29510 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
29520 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
29530 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
29540 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
29550 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
29560 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
29570 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
29580 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
29590 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
295a0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
295b0 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
295c0 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
295d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
295e0 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
295f0 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
29600 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
29610 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
29620 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
29630 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
29640 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
29650 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
29660 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
29670 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
29680 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
29690 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
296a0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
296b0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
296c0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
296d0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
296e0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
296f0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
29700 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
29710 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
29720 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
29730 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
29740 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
29750 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
29760 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
29770 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
29780 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
29790 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
297a0 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
297b0 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
297c0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
297d0 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
297e0 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
297f0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
29800 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
29810 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
29820 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
29830 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
29840 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
29850 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
29860 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
29870 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
29880 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
29890 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
298a0 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
298b0 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
298c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
298d0 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
298e0 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
298f0 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
29900 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
29910 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
29920 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
29930 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
29940 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29950 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
29960 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
29970 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
29980 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
29990 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
299a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
299b0 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
299c0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
299d0 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
299e0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
299f0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
29a00 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
29a10 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
29a20 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
29a30 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
29a40 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
29a50 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
29a60 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
29a70 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
29a80 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
29a90 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
29aa0 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
29ab0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
29ac0 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
29ad0 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
29ae0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
29af0 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
29b00 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
29b10 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
29b20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
29b30 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
29b40 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
29b50 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
29b60 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c  esirable..*/.SQL
29b70 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
29b80 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
29b90 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
29ba0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
29bb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
29bc0 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ram);.SQLITE_API
29bd0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69   int sqlite3_uri
29be0 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
29bf0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
29c00 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
29c10 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53  int bDefault);.S
29c20 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
29c30 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
29c40 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
29c50 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
29c60 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
29c70 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
29c80 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
29c90 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
29ca0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
29cb0 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  3.**.** ^If the 
29cc0 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69  most recent sqli
29cd0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
29ce0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a  ssociated with .
29cf0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
29d00 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65  nection] D faile
29d10 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  d, then the sqli
29d20 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69  te3_errcode(D) i
29d30 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
29d40 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
29d50 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
29d60 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
29d70 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74  t code] for that
29d80 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a  .** API call..**
29d90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
29da0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
29db0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
29dc0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
29dd0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
29de0 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
29df0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
29e00 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
29e10 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
29e20 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
29e30 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  sabled..**.** Th
29e40 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
29e50 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 72 72  d by sqlite3_err
29e60 63 6f 64 65 28 29 20 61 6e 64 2f 6f 72 0a 2a 2a  code() and/or.**
29e70 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
29e80 64 5f 65 72 72 63 6f 64 65 28 29 20 6d 69 67 68  d_errcode() migh
29e90 74 20 63 68 61 6e 67 65 20 77 69 74 68 20 65 61  t change with ea
29ea0 63 68 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20  ch API call..** 
29eb0 45 78 63 65 70 74 2c 20 74 68 65 72 65 20 61 72  Except, there ar
29ec0 65 20 73 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  e some interface
29ed0 73 20 74 68 61 74 20 61 72 65 20 67 75 61 72 61  s that are guara
29ee0 6e 74 65 65 64 20 74 6f 20 6e 65 76 65 72 0a 2a  nteed to never.*
29ef0 2a 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  * change the val
29f00 75 65 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  ue of the error 
29f10 63 6f 64 65 2e 20 20 54 68 65 20 65 72 72 6f 72  code.  The error
29f20 2d 63 6f 64 65 20 70 72 65 73 65 72 76 69 6e 67  -code preserving
29f30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
29f40 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  re:.**.** <ul>.*
29f50 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65  * <li> sqlite3_e
29f60 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e  rrcode().** <li>
29f70 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
29f80 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c  d_errcode().** <
29f90 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  li> sqlite3_errm
29fa0 73 67 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  sg().** <li> sql
29fb0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 0a  ite3_errmsg16().
29fc0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
29fd0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
29fe0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
29ff0 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
2a000 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
2a010 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
2a020 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
2a030 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
2a040 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
2a050 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2a060 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
2a070 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
2a080 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
2a090 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
2a0a0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2a0b0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
2a0c0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
2a0d0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
2a0e0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
2a0f0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
2a100 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
2a110 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
2a120 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
2a130 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2a140 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
2a150 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
2a160 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
2a170 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
2a180 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a190 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
2a1a0 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
2a1b0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
2a1c0 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
2a1d0 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
2a1e0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
2a1f0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2a200 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
2a210 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
2a220 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
2a230 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
2a240 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
2a250 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
2a260 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
2a270 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
2a280 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
2a290 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
2a2a0 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
2a2b0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
2a2c0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
2a2d0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
2a2e0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
2a2f0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
2a300 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
2a310 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
2a320 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
2a330 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
2a340 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
2a350 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
2a360 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
2a370 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
2a380 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
2a390 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
2a3a0 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
2a3b0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
2a3c0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
2a3d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a3e0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
2a3f0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
2a400 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
2a410 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
2a420 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
2a430 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
2a440 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
2a450 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
2a460 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
2a470 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
2a480 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
2a490 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
2a4a0 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
2a4b0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
2a4c0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
2a4d0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
2a4e0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
2a4f0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
2a500 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
2a510 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
2a520 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a530 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
2a540 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
2a550 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
2a560 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
2a570 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
2a580 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2a590 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
2a5a0 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
2a5b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
2a5c0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
2a5d0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
2a5e0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2a5f0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
2a600 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
2a610 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2a620 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
2a630 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
2a640 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2a650 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
2a660 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
2a670 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
2a680 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2a690 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
2a6a0 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
2a6b0 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
2a6c0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
2a6d0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
2a6e0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
2a6f0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
2a700 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
2a710 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65  t that.** has be
2a720 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  en compiled into
2a730 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64   binary form and
2a740 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20   is ready to be 
2a750 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  evaluated..**.**
2a760 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53   Think of each S
2a770 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
2a780 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75  a separate compu
2a790 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68  ter program.  Th
2a7a0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
2a7b0 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65  L text is source
2a7c0 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72   code.  A prepar
2a7d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
2a7e0 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63  ect .** is the c
2a7f0 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63  ompiled object c
2a800 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75  ode.  All SQL mu
2a810 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
2a820 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72  into a.** prepar
2a830 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66  ed statement bef
2a840 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75  ore it can be ru
2a850 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  n..**.** The lif
2a860 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65  e-cycle of a pre
2a870 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a880 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67  object usually g
2a890 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  oes like this:.*
2a8a0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2a8b0 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65  > Create the pre
2a8c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a8d0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
2a8e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a8f0 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ()]..** <li> Bin
2a900 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72  d values to [par
2a910 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
2a920 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2a930 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
2a940 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
2a950 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
2a960 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2a970 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
2a980 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
2a990 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65  i> Reset the pre
2a9a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2a9b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2a9c0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
2a9d0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
2a9e0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
2a9f0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
2aa00 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
2aa10 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
2aa20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2aa30 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
2aa40 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  /ol>.*/.typedef 
2aa50 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
2aa60 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
2aa70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2aa80 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
2aa90 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ts.** METHOD: sq
2aaa0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lite3.**.** ^(Th
2aab0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
2aac0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
2aad0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
2aae0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
2aaf0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
2ab00 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
2ab10 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
2ab20 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2ab30 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
2ab40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
2ab50 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
2ab60 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
2ab70 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
2ab80 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
2ab90 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
2aba0 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
2abb0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
2abc0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
2abd0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
2abe0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
2abf0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2ac00 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
2ac10 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
2ac20 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
2ac30 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
2ac40 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
2ac50 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
2ac60 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
2ac70 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
2ac80 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
2ac90 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
2aca0 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
2acb0 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
2acc0 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
2acd0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
2ace0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
2acf0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
2ad00 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
2ad10 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
2ad20 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
2ad30 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
2ad40 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
2ad50 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
2ad60 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
2ad70 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
2ad80 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
2ad90 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
2ada0 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
2adb0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
2adc0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
2add0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
2ade0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
2adf0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
2ae00 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
2ae10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
2ae20 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
2ae30 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
2ae40 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
2ae50 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
2ae60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
2ae70 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
2ae80 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
2ae90 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
2aea0 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
2aeb0 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
2aec0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2aed0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
2aee0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
2aef0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
2af00 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
2af10 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
2af20 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
2af30 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
2af40 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
2af50 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
2af60 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
2af70 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
2af80 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
2af90 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
2afa0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
2afb0 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
2afc0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
2afd0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
2afe0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
2aff0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
2b000 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
2b010 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
2b020 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
2b030 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
2b040 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
2b050 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
2b060 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
2b070 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
2b080 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
2b090 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
2b0a0 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
2b0b0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
2b0c0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
2b0d0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
2b0e0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
2b0f0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
2b100 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
2b110 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
2b120 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
2b130 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
2b140 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
2b150 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
2b160 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
2b170 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
2b180 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
2b190 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2b1a0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
2b1b0 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
2b1c0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
2b1d0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
2b1e0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
2b1f0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
2b200 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
2b210 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
2b220 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
2b230 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
2b240 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2b250 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
2b260 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
2b270 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
2b280 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b290 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
2b2a0 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
2b2b0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
2b2c0 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
2b2d0 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
2b2e0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2b2f0 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
2b300 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
2b310 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
2b320 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
2b330 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
2b340 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
2b350 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
2b360 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
2b370 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
2b380 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
2b390 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
2b3a0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
2b3b0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
2b3c0 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
2b3d0 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
2b3e0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
2b3f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2b400 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2b410 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
2b420 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2b430 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
2b440 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
2b450 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
2b460 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
2b470 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2b480 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
2b490 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2b4a0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
2b4b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2b4c0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2b4d0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2b4e0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
2b4f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2b500 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
2b510 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b520 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
2b530 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2b540 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
2b550 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
2b560 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
2b570 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
2b580 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
2b590 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
2b5a0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2b5b0 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
2b5c0 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
2b5d0 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
2b5e0 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
2b5f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2b600 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
2b610 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2b620 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
2b630 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2b640 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
2b650 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
2b660 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
2b670 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2b680 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
2b690 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
2b6a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2b6b0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2b6c0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
2b6d0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2b6e0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
2b6f0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
2b700 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
2b710 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2b720 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
2b730 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2b740 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
2b750 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2b760 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
2b770 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
2b780 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
2b790 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
2b7a0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
2b7b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  QL statement.  I
2b7c0 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  f [sqlite3_prepa
2b7d0 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74  re_v2()] or.** t
2b7e0 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74 72  he equivalent tr
2b7f0 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ies to allocate 
2b800 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20 74  space for more t
2b810 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f 70  han this many op
2b820 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69  codes.** in a si
2b830 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73 74  ngle prepared st
2b840 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49  atement, an SQLI
2b850 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69  TE_NOMEM error i
2b860 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
2b870 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2b880 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
2b890 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
2b8a0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2b8b0 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
2b8c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2b8d0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2b8e0 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
2b8f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2b900 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
2b910 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
2b920 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
2b930 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
2b940 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2b950 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
2b960 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2b970 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
2b980 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2b990 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
2b9a0 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
2b9b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
2b9c0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2b9d0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2b9e0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
2b9f0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
2ba00 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2ba10 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
2ba20 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
2ba30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2ba40 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2ba50 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
2ba60 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2ba70 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2ba80 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
2ba90 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
2baa0 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
2bab0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
2bac0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
2bad0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2bae0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
2baf0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
2bb00 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2bb10 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
2bb20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2bb30 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
2bb40 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
2bb50 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2bb60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
2bb70 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28  KER_THREADS]] ^(
2bb80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2bb90 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c  _WORKER_THREADS<
2bba0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2bbb0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2bbc0 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b  f auxiliary work
2bbd0 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20  er threads that 
2bbe0 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65  a single.** [pre
2bbf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bc00 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e   may start.</dd>
2bc10 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
2bc20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2bc30 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
2bc40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
2bc50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2bc60 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
2bc70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
2bc80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bc90 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
2bca0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bcb0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2bcc0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2bcd0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2bce0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
2bcf0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
2bd00 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
2bd10 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2bd20 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
2bd30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bd40 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
2bd50 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2bd60 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
2bd70 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
2bd80 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
2bd90 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
2bda0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
2bdb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
2bdc0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
2bdd0 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
2bde0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2bdf0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
2be00 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
2be10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
2be20 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
2be30 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
2be40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  e SQLITE_LIMIT_W
2be50 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20  ORKER_THREADS   
2be60 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a          11../*.*
2be70 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
2be80 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  are Flags.**.** 
2be90 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2bea0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 66  define various f
2beb0 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20 62 65  lags that can be
2bec0 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
2bed0 22 70 72 65 70 46 6c 61 67 73 22 20 70 61 72 61  "prepFlags" para
2bee0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73 71  meter of the [sq
2bef0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2bf00 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
2bf10 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2bf20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ()] interfaces..
2bf30 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20  **.** New flags 
2bf40 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
2bf50 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2bf60 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2bf70 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
2bf80 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2bf90 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  TENT]] ^(<dt>SQL
2bfa0 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2bfb0 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  ISTENT</dt>.** <
2bfc0 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52  dd>The SQLITE_PR
2bfd0 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2bfe0 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74 20   flag is a hint 
2bff0 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c 61  to the query pla
2c000 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  nner.** that the
2c010 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2c020 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74 61  ent will be reta
2c030 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20  ined for a long 
2c040 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62  time and.** prob
2c050 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e 79  ably reused many
2c060 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f   times.)^ ^Witho
2c070 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b 73  ut this flag, [s
2c080 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c090 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  3()].** and [sql
2c0a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2c0b0 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61 74  3()] assume that
2c0c0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2c0d0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a  atement will .**
2c0e0 20 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f 6e   be used just on
2c0f0 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 20  ce or at most a 
2c100 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74 68  few times and th
2c110 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  en destroyed usi
2c120 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
2c130 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74  inalize()] relat
2c140 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20  ively soon. The 
2c150 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
2c160 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f  tation acts.** o
2c170 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79 20 61  n this hint by a
2c180 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65 20  voiding the use 
2c190 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  of [lookaside me
2c1a0 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20  mory] so as not 
2c1b0 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74 68  to.** deplete th
2c1c0 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65 20  e limited store 
2c1d0 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  of lookaside mem
2c1e0 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65 72 73  ory. Future vers
2c1f0 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ions of.** SQLit
2c200 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68 69  e may act on thi
2c210 73 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e 74  s hint different
2c220 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ly..** </dl>.*/.
2c230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
2c240 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2c250 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  T              0
2c260 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x01../*.** CAPI3
2c270 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
2c280 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2c290 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2c2a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2c2b0 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  iler}.** METHOD:
2c2c0 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53   sqlite3.** CONS
2c2d0 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
2c2e0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  _stmt.**.** To e
2c2f0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74  xecute an SQL st
2c300 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74  atement, it must
2c310 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
2c320 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
2c330 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
2c340 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
2c350 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c  e routines.  Or,
2c360 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
2c370 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2c380 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74  ** are construct
2c390 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65  ors for the [pre
2c3a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c3b0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54   object..**.** T
2c3c0 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f 75  he preferred rou
2c3d0 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b  tine to use is [
2c3e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c3f0 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b  v2()].  The.** [
2c400 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2c410 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
2c420 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c  legacy and shoul
2c430 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a  d be avoided..**
2c440 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c450 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65  e_v3()] has an e
2c460 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73 22  xtra "prepFlags"
2c470 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20   option that is 
2c480 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63  used.** for spec
2c490 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  ial purposes..**
2c4a0 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74  .** The use of t
2c4b0 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61  he UTF-8 interfa
2c4c0 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65 64  ces is preferred
2c4d0 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72 72  , as SQLite curr
2c4e0 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c  ently.** does al
2c4f0 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20  l parsing using 
2c500 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d  UTF-8.  The UTF-
2c510 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  16 interfaces ar
2c520 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73  e provided.** as
2c530 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20   a convenience. 
2c540 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65   The UTF-16 inte
2c550 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63  rfaces work by c
2c560 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a  onverting the.**
2c570 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f   input text into
2c580 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76   UTF-8, then inv
2c590 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73  oking the corres
2c5a0 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e  ponding UTF-8 in
2c5b0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
2c5c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2c5d0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
2c5e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c5f0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
2c600 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
2c610 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2c620 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2c630 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
2c640 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
2c650 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
2c660 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
2c670 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
2c680 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
2c690 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
2c6a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
2c6b0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
2c6c0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2c6d0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
2c6e0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
2c6f0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
2c700 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2c710 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  re(), sqlite3_pr
2c720 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61  epare_v2(),.** a
2c730 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2c740 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v3().** inter
2c750 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
2c760 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2c770 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65  pare16(), sqlite
2c780 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2c790 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2c7a0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20  _prepare16_v3() 
2c7b0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
2c7c0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
2c7d0 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61  argument is nega
2c7e0 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20  tive, then zSql 
2c7f0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
2c800 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
2c810 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
2c820 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76  nByte is positiv
2c830 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
2c840 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2c850 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
2c860 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20  Sql.  ^If nByte 
2c870 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f  is zero, then no
2c880 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2c890 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61  tement is genera
2c8a0 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ted..** If the c
2c8b0 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74  aller knows that
2c8c0 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
2c8d0 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
2c8e0 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  inated, then.** 
2c8f0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
2c900 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
2c910 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e  antage to passin
2c920 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
2c930 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
2c940 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2c950 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
2c960 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
2c970 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
2c980 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  nul-terminator..
2c990 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
2c9a0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
2c9b0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
2c9c0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
2c9d0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
2c9e0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
2c9f0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
2ca00 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
2ca10 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2ca20 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
2ca30 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
2ca40 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
2ca50 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
2ca60 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
2ca70 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
2ca80 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
2ca90 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
2caa0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
2cab0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
2cac0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2cad0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
2cae0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
2caf0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
2cb00 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
2cb10 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
2cb20 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
2cb30 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
2cb40 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
2cb50 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
2cb60 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
2cb70 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
2cb80 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
2cb90 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
2cba0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
2cbb0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
2cbc0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
2cbd0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
2cbe0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
2cbf0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
2cc00 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2cc10 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
2cc20 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
2cc30 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
2cc40 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2cc50 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
2cc60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2cc70 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
2cc80 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2cc90 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
2cca0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
2ccb0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2ccc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2ccd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2cce0 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2ccf0 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65  are_v3(), sqlite
2cd00 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2cd10 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2cd20 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20  _prepare16_v3() 
2cd30 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
2cd40 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
2cd50 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
2cd60 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e  .** The older in
2cd70 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74 65  terfaces (sqlite
2cd80 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
2cd90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cda0 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61  6()).** are reta
2cdb0 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
2cdc0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
2cdd0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
2cde0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
2cdf0 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20  ** ^In the "vX" 
2ce00 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
2ce10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ce20 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
2ce30 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
2ce40 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2ce50 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
2ce60 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
2ce70 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
2ce80 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
2ce90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2cea0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
2ceb0 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
2cec0 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
2ced0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
2cee0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2cef0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2cf00 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
2cf10 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
2cf20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
2cf30 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
2cf40 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
2cf50 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
2cf60 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2cf70 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
2cf80 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
2cf90 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
2cfa0 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
2cfb0 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
2cfc0 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
2cfd0 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
2cfe0 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
2cff0 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
2d000 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
2d010 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
2d020 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
2d030 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
2d040 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
2d050 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
2d060 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
2d070 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
2d080 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
2d090 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
2d0a0 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
2d0b0 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
2d0c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2d0d0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
2d0e0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
2d0f0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2d100 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
2d110 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
2d120 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
2d130 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
2d140 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2d150 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
2d160 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
2d170 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
2d180 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
2d190 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
2d1a0 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
2d1b0 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
2d1c0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
2d1d0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
2d1e0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
2d1f0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
2d200 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2d210 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2d220 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
2d230 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
2d240 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
2d250 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
2d260 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2d270 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
2d280 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
2d290 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
2d2a0 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
2d2b0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
2d2c0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
2d2d0 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
2d2e0 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
2d2f0 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
2d300 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
2d310 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2d320 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
2d330 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
2d340 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d350 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
2d360 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
2d370 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
2d380 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
2d390 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
2d3a0 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
2d3b0 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
2d3c0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2d3d0 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
2d3e0 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
2d3f0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
2d400 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
2d410 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
2d420 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2d430 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
2d440 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
2d450 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
2d460 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
2d470 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
2d480 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
2d490 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  d..** </li>.** <
2d4a0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73  /ol>.**.** <p>^s
2d4b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d4c0 33 28 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d  3() differs from
2d4d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d4e0 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61  _v2() only in ha
2d4f0 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72  ving.** the extr
2d500 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61  a prepFlags para
2d510 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 73 20  meter, which is 
2d520 61 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73  a bit array cons
2d530 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f  isting of zero o
2d540 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65  r.** more of the
2d550 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45   [SQLITE_PREPARE
2d560 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49  _PERSISTENT|SQLI
2d570 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c  TE_PREPARE_*] fl
2d580 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ags.  ^The.** sq
2d590 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d5a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
2d5b0 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  ks exactly the s
2d5c0 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65  ame as.** sqlite
2d5d0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 77  3_prepare_v3() w
2d5e0 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46  ith a zero prepF
2d5f0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a  lags parameter..
2d600 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2d610 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2d620 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2d630 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2d640 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2d650 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2d660 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2d670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2d680 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2d690 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2d6a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2d6b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2d6c0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2d6d0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2d6e0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2d6f0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2d700 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2d710 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2d720 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2d730 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2d740 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2d750 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d760 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d770 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  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 63 68 61 72   */.  const char
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 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2d7e0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2d7f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2d800 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2d810 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2d820 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2d830 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2d840 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2d850 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2d860 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2d870 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2d880 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2d890 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2d8a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d8b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d8c0 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2d8d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2d8e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2d8f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2d900 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2d910 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2d920 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2d930 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2d940 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2d950 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2d960 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2d970 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e  */.  unsigned in
2d980 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20  t prepFlags, /* 
2d990 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c  Zero or more SQL
2d9a0 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61  ITE_PREPARE_ fla
2d9b0 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  gs */.  sqlite3_
2d9c0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2d9d0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2d9e0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2d9f0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2da00 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2da10 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2da20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2da30 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2da40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
2da50 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
2da60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2da70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2da80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2da90 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2daa0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2dab0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2dac0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2dad0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2dae0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2daf0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2db00 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2db10 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2db20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2db30 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2db40 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2db50 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2db60 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2db70 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2db80 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2db90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
2dba0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2dbb0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2dbc0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2dbd0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2dbe0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2dbf0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2dc00 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2dc10 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2dc20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2dc30 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2dc40 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2dc50 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2dc60 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2dc70 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2dc80 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2dc90 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2dca0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2dcb0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2dcc0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2dcd0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
2dce0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2dcf0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a  3_prepare16_v3(.
2dd00 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2dd10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2dd20 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2dd30 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2dd40 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2dd50 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2dd60 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2dd70 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2dd80 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2dd90 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2dda0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2ddb0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72   unsigned int pr
2ddc0 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f  epFlags, /* Zero
2ddd0 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f   or more SQLITE_
2dde0 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a  PREPARE_ flags *
2ddf0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2de00 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2de10 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2de20 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2de30 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2de40 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2de50 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2de60 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2de70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2de80 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
2de90 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d  atement SQL.** M
2dea0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2deb0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2dec0 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e  qlite3_sql(P) in
2ded0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2dee0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63  a pointer to a c
2def0 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38  opy of the UTF-8
2df00 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
2df10 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65  d to create [pre
2df20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2df30 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63   P if P was.** c
2df40 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
2df50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2df60 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
2df70 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v3()],.** [sq
2df80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2df90 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  v2()], or [sqlit
2dfa0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2dfb0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
2dfc0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2dfd0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2dfe0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2dff0 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74  to a UTF-8.** st
2e000 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
2e010 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20  the SQL text of 
2e020 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e030 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f  nt P with.** [bo
2e040 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20  und parameters] 
2e050 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  expanded..**.** 
2e060 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2e070 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
2e080 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65  tement is create
2e090 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a  d using the SQL.
2e0a0 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20  ** text "SELECT 
2e0b0 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69  $abc,:xyz" and i
2e0c0 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63  f parameter $abc
2e0d0 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74   is bound to int
2e0e0 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64  eger 2345.** and
2e0f0 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20   parameter :xyz 
2e100 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e  is unbound, then
2e110 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77   sqlite3_sql() w
2e120 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  ill return.** th
2e130 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e  e original strin
2e140 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  g, "SELECT $abc,
2e150 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65  :xyz" but sqlite
2e160 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2e170 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2e180 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c  "SELECT 2345,NUL
2e190 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  L".)^.**.** ^The
2e1a0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2e1b0 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63  d_sql() interfac
2e1c0 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
2e1d0 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d  f insufficient m
2e1e0 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69  emory.** is avai
2e1f0 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68  lable to hold th
2e200 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20  e result, or if 
2e210 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64  the result would
2e220 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74   exceed the.** t
2e230 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e  he maximum strin
2e240 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69  g length determi
2e250 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49  ned by the [SQLI
2e260 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2e270 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
2e280 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
2e290 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
2e2a0 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74  ime option limit
2e2b0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  s the size of.**
2e2c0 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72   bound parameter
2e2d0 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54   expansions.  ^T
2e2e0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2e2f0 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
2e300 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61  ime.** option ca
2e310 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70  uses sqlite3_exp
2e320 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61  anded_sql() to a
2e330 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c  lways return NUL
2e340 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74  L..**.** ^The st
2e350 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
2e360 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2e370 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51  is managed by SQ
2e380 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61  Lite and is.** a
2e390 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2e3a0 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70  ed when the prep
2e3b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2e3c0 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  s finalized..** 
2e3d0 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75  ^The string retu
2e3e0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2e3f0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c  expanded_sql(P),
2e400 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61   on the other ha
2e410 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e  nd,.** is obtain
2e420 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2e430 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d  _malloc()] and m
2e440 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74  ust be free by t
2e450 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
2e460 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20  * by passing it 
2e470 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
2e480 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2e490 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2e4a0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2e4b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2e4c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
2e4d0 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2e4e0 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2e4f0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2e500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2e510 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
2e520 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
2e530 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
2e540 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e550 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2e560 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2e570 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
2e580 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2e590 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2e5a0 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
2e5b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2e5c0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
2e5d0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
2e5e0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
2e5f0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2e600 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
2e610 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
2e620 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e630 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
2e640 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
2e650 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
2e660 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2e670 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
2e680 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
2e690 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2e6a0 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
2e6b0 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
2e6c0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
2e6d0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
2e6e0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
2e6f0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
2e700 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
2e710 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
2e720 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2e730 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
2e740 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
2e750 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2e760 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
2e770 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
2e780 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
2e790 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
2e7a0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
2e7b0 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
2e7c0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
2e7d0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2e7e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
2e7f0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
2e800 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2e810 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
2e820 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
2e830 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
2e840 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
2e850 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
2e860 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
2e870 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
2e880 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
2e890 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
2e8a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2e8b0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2e8c0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
2e8d0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
2e8e0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
2e8f0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
2e900 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2e910 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
2e920 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
2e930 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
2e940 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
2e950 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
2e960 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
2e970 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
2e980 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
2e990 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
2e9a0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2e9b0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2e9c0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
2e9d0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
2e9e0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
2e9f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
2ea00 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
2ea10 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
2ea20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
2ea30 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
2ea40 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2ea50 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
2ea60 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  k..** ^The sqlit
2ea70 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2ea80 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2ea90 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42  urns true for [B
2eaa0 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b  EGIN] since.** [
2eab0 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65  BEGIN] merely se
2eac0 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67  ts internal flag
2ead0 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49  s, but the [BEGI
2eae0 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54  N|BEGIN IMMEDIAT
2eaf0 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e  E] and.** [BEGIN
2eb00 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45  |BEGIN EXCLUSIVE
2eb10 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f  ] commands do to
2eb20 75 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  uch the database
2eb30 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74   and so.** sqlit
2eb40 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2eb50 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  () returns false
2eb60 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61   for those comma
2eb70 6e 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  nds..*/.SQLITE_A
2eb80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
2eb90 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
2eba0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ebb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ebc0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2ebd0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2ebe0 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
2ebf0 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eset.** METHOD: 
2ec00 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2ec10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ec20 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
2ec30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2ec40 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
2ec50 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
2ec60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2ec70 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
2ec80 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
2ec90 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2eca0 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
2ecb0 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74  as neither run t
2ecc0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65  o completion (re
2ecd0 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2ece0 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71  E_DONE] from [sq
2ecf0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20  lite3_step(S)]) 
2ed00 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  nor.** been rese
2ed10 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2ed20 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
2ed30 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2ed40 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
2ed50 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
2ed60 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
2ed70 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
2ed80 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
2ed90 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
2eda0 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
2edb0 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
2edc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2edd0 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
2ede0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2edf0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2ee00 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
2ee10 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
2ee20 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2ee30 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
2ee40 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
2ee50 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
2ee60 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
2ee70 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
2ee80 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
2ee90 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
2eea0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
2eeb0 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
2eec0 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
2eed0 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
2eee0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
2eef0 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
2ef00 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
2ef10 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
2ef20 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
2ef30 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
2ef40 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
2ef50 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ef60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2ef70 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
2ef80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ef90 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
2efa0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
2efb0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2efc0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2efd0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
2efe0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2eff0 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
2f000 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
2f010 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2f020 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
2f030 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
2f040 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
2f050 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
2f060 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
2f070 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
2f080 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
2f090 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
2f0a0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
2f0b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2f0c0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
2f0d0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
2f0e0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
2f0f0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
2f100 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
2f110 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f120 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
2f130 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
2f140 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
2f150 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
2f160 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
2f170 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f180 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
2f190 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
2f1a0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
2f1b0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
2f1c0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2f1d0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
2f1e0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
2f1f0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
2f200 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
2f210 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
2f220 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
2f230 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
2f240 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f250 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
2f260 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
2f270 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
2f280 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
2f290 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
2f2a0 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
2f2b0 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
2f2c0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2f2d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2f2e0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
2f2f0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
2f300 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
2f310 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
2f320 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
2f330 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
2f340 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
2f350 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
2f360 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2f370 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
2f380 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
2f390 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
2f3a0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2f3b0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
2f3c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2f3d0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
2f3e0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
2f3f0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
2f400 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
2f410 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
2f420 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
2f430 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
2f440 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
2f450 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
2f460 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
2f470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2f480 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
2f490 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2f4a0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
2f4b0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
2f4c0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2f4d0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2f4e0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2f4f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2f500 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
2f510 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
2f520 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
2f530 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
2f540 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
2f550 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
2f560 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
2f570 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
2f580 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
2f590 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2f5a0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2f5b0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2f5c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2f5d0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
2f5e0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
2f5f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2f600 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2f610 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
2f620 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
2f630 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
2f640 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2f650 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2f660 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2f670 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
2f680 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2f690 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2f6a0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2f6b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2f6c0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
2f6d0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
2f6e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f6f0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
2f700 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 61 73   only be used as
2f710 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f   arguments.** to
2f720 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2f730 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69  _value()], [sqli
2f740 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2f750 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2f760 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e  e3_value_dup()].
2f770 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2f780 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
2f790 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2f7a0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
2f7b0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2f7c0 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
2f7d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2f7e0 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
2f7f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2f800 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  alue sqlite3_val
2f810 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2f820 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2f830 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2f840 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2f850 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2f860 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2f870 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2f880 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2f890 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2f8a0 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2f8b0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2f8c0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2f8d0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2f8e0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2f8f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2f900 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2f910 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2f920 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2f930 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2f940 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2f950 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2f960 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2f970 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2f980 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2f990 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2f9a0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2f9b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2f9c0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2f9d0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2f9e0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2f9f0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2fa00 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2fa10 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2fa20 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2fa30 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2fa40 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2fa50 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2fa60 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2fa70 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2fa80 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
2fa90 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
2faa0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
2fab0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
2fac0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
2fad0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2fae0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
2faf0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
2fb00 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
2fb10 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
2fb20 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
2fb30 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2fb40 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2fb50 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2fb60 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2fb70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2fb80 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2fb90 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2fba0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2fbb0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2fbc0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2fbd0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2fbe0 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2fbf0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2fc00 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2fc10 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2fc20 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2fc30 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2fc40 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2fc50 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2fc60 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2fc70 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2fc80 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2fc90 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2fca0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2fcb0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2fcc0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2fcd0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2fce0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2fcf0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2fd00 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2fd10 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2fd20 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2fd30 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2fd40 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2fd50 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2fd60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2fd70 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2fd80 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2fd90 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2fda0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2fdb0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2fdc0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2fdd0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2fde0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2fdf0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2fe00 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2fe10 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2fe20 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2fe30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2fe40 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2fe50 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2fe60 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2fe70 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2fe80 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2fe90 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2fea0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2feb0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2fec0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2fed0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2fee0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2fef0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2ff00 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2ff10 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2ff20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2ff30 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2ff40 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2ff50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ff60 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2ff70 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2ff80 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2ff90 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2ffa0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2ffb0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2ffc0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2ffd0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2ffe0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2fff0 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
30000 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
30010 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
30020 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
30030 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
30040 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
30050 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
30060 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
30070 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
30080 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
30090 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
300a0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
300b0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
300c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
300d0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
300e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
300f0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
30100 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
30110 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
30120 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
30130 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
30140 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
30150 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
30160 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
30170 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
30180 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
30190 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
301a0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
301b0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
301c0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
301d0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
301e0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
301f0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
30200 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
30210 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
30220 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
30230 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
30240 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
30250 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
30260 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
30270 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
30280 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
30290 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
302a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
302b0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
302c0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
302d0 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
302e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
302f0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
30300 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
30310 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
30320 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
30330 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
30340 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
30350 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
30360 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
30370 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
30380 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
30390 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
303a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
303b0 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
303c0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
303d0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
303e0 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
303f0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
30400 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
30410 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
30420 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
30430 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
30440 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
30450 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
30460 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
30470 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
30480 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
30490 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
304a0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
304b0 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
304c0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
304d0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
304e0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
304f0 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
30500 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
30510 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
30520 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
30530 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
30540 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
30550 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
30560 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
30570 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
30580 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
30590 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
305a0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
305b0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
305c0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
305d0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
305e0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
305f0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
30600 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
30610 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
30620 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
30630 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
30640 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
30650 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
30660 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
30670 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
30680 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
30690 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
306a0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
306b0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
306c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
306d0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
306e0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
306f0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
30700 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
30710 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
30720 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
30730 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
30740 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
30750 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
30760 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
30770 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
30780 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
30790 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
307a0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
307b0 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
307c0 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
307d0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
307e0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
307f0 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
30800 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
30810 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
30820 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
30830 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
30840 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
30850 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
30860 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
30870 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
30880 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
30890 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
308a0 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
308b0 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
308c0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
308d0 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
308e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
308f0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
30900 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
30910 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
30920 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
30930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30940 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
30950 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
30960 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
30970 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
30980 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
30990 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
309a0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
309b0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
309c0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
309d0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
309e0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
309f0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
30a00 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
30a10 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
30a20 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
30a30 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
30a40 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
30a50 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
30a60 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
30a70 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
30a80 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
30a90 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
30aa0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
30ab0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
30ac0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
30ad0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
30ae0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OB..**.** ^The s
30af0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
30b00 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72  ter(S,I,P,T,D) r
30b10 6f 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68  outine causes th
30b20 65 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e I-th parameter
30b30 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   in.** [prepared
30b40 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f   statement] S to
30b50 20 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c   have an SQL val
30b60 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20  ue of NULL, but 
30b70 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73  to also be.** as
30b80 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
30b90 65 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74  e pointer P of t
30ba0 79 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69  ype T.  ^D is ei
30bb0 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
30bc0 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e  ter or.** a poin
30bd0 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63  ter to a destruc
30be0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72  tor function for
30bf0 20 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c   P. ^SQLite will
30c00 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64   invoke the.** d
30c10 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
30c20 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
30c30 6e 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20  nt of P when it 
30c40 69 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  is finished usin
30c50 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70  g.** P.  The T p
30c60 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
30c70 62 65 20 61 20 73 74 61 74 69 63 20 73 74 72 69  be a static stri
30c80 6e 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61  ng, preferably a
30c90 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72   string.** liter
30ca0 61 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f  al. The sqlite3_
30cb0 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72  bind_pointer() r
30cc0 6f 75 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f  outine is part o
30cd0 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65  f the.** [pointe
30ce0 72 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66  r passing interf
30cf0 61 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53  ace] added for S
30d00 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a  QLite 3.20.0..**
30d10 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
30d20 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
30d30 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
30d40 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
30d50 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
30d60 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
30d70 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
30d80 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
30d90 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
30da0 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
30db0 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
30dc0 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
30dd0 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
30de0 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
30df0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
30e00 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
30e10 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
30e20 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
30e30 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
30e40 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
30e50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
30e60 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
30e70 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
30e80 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
30e90 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
30ea0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
30eb0 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
30ec0 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
30ed0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30ee0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
30ef0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
30f00 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
30f10 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
30f20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
30f30 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
30f40 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
30f50 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
30f60 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
30f70 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
30f80 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
30f90 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
30fa0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
30fb0 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
30fc0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
30fd0 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
30fe0 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
30ff0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
31000 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
31010 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
31020 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
31030 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
31040 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
31050 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
31060 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
31070 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
31080 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
31090 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
310a0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
310b0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
310c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
310d0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
310e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
310f0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
31100 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
31110 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
31120 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
31130 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
31140 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
31150 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
31160 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
31170 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
31180 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
31190 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
311a0 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
311b0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
311c0 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
311d0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
311e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
311f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
31200 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31210 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
31220 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31230 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
31240 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31250 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
31260 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31270 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
31280 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31290 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
312a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
312b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
312c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
312d0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
312e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
312f0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
31300 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
31310 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
31320 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
31330 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
31340 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
31350 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31360 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
31370 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
31380 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
31390 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
313a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
313b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
313c0 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
313d0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
313e0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
313f0 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
31400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31410 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
31420 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
31430 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f  coding);.SQLITE_
31440 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31450 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
31460 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
31470 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
31480 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
31490 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
314a0 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65  d_pointer(sqlite
314b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f  3_stmt*, int, vo
314c0 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  id*, const char*
314d0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
314e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
314f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
31500 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
31510 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
31520 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
31530 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
31540 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
31550 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
31560 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
31570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31580 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
31590 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
315a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
315b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
315c0 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
315d0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
315e0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
315f0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
31600 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31610 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
31620 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
31630 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
31640 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
31650 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
31660 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
31670 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
31680 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
31690 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
316a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
316b0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
316c0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
316d0 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
316e0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
316f0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
31700 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
31710 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
31720 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
31730 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
31740 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
31750 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
31760 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
31770 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
31780 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
31790 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
317a0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
317b0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
317c0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
317d0 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
317e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
317f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
31800 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
31810 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
31820 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
31830 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
31840 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
31850 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
31860 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31870 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
31880 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
31890 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
318a0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
318b0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
318c0 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  er.** METHOD: sq
318d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
318e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
318f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
31900 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
31910 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
31920 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
31930 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
31940 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
31950 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
31960 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
31970 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
31980 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
31990 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
319a0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
319b0 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
319c0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
319d0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
319e0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
319f0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
31a00 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
31a10 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
31a20 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
31a30 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
31a40 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
31a50 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
31a60 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
31a70 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
31a80 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
31a90 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
31aa0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
31ab0 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
31ac0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
31ad0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
31ae0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
31af0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
31b00 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
31b10 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
31b20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
31b30 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
31b40 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
31b50 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
31b60 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
31b70 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
31b80 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
31b90 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
31ba0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
31bb0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
31bc0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
31bd0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
31be0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
31bf0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
31c00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
31c10 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
31c20 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
31c30 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
31c40 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
31c50 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
31c60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
31c70 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
31c80 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
31c90 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
31ca0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
31cb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
31cc0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
31cd0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
31ce0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
31cf0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
31d00 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
31d10 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
31d20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
31d30 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
31d40 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
31d50 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ame.** METHOD: s
31d60 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31d70 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
31d80 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
31d90 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
31da0 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
31db0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
31dc0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
31dd0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
31de0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
31df0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
31e00 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
31e10 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
31e20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
31e30 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
31e40 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
31e50 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
31e60 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
31e70 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
31e80 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
31e90 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
31ea0 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
31eb0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
31ec0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
31ed0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
31ee0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
31ef0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
31f00 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
31f10 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
31f20 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
31f30 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
31f40 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31f50 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
31f60 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
31f70 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
31f80 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  e()]..*/.SQLITE_
31f90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31fa0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
31fb0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
31fc0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
31fd0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
31fe0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
31ff0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
32000 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
32010 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
32020 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32030 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
32040 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
32050 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
32060 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
32070 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
32080 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
32090 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
320a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
320b0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
320c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
320d0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
320e0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
320f0 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
32100 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65   int sqlite3_cle
32110 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
32120 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
32130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
32140 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
32150 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
32160 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32170 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
32180 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
32190 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
321a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
321b0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
321c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
321d0 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72  ent]. ^If this r
321e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
321f0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
32200 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
32210 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e  tatement] return
32220 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65  s no data (for e
32230 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
32240 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72  E])..** ^However
32250 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 74  , just because t
32260 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
32270 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
32280 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a  umber does not.*
32290 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20  * mean that one 
322a0 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20  or more rows of 
322b0 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74  data will be ret
322c0 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43  urned.  ^A SELEC
322d0 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  T statement.** w
322e0 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20  ill always have 
322f0 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74  a positive sqlit
32300 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
32310 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20  ) but depending 
32320 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20  on the.** WHERE 
32330 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
32340 74 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65  ts and the table
32350 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67   content, it mig
32360 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77  ht return no row
32370 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
32380 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
32390 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
323a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
323b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
323c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
323d0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
323e0 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
323f0 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
32400 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
32410 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
32420 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
32430 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
32440 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
32450 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
32460 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
32470 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
32480 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
32490 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
324a0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
324b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
324c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
324d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
324e0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
324f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32500 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
32510 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
32520 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
32530 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
32540 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
32550 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
32560 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
32570 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
32580 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
32590 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
325a0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
325b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
325c0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
325d0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
325e0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
325f0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
32600 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
32610 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
32620 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
32630 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
32640 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
32650 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
32660 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
32670 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
32680 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
32690 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
326a0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
326b0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
326c0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
326d0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
326e0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
326f0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
32700 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
32710 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
32720 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
32730 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
32740 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
32750 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
32760 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
32770 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
32780 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
32790 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
327a0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
327b0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
327c0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
327d0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
327e0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
327f0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
32800 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
32810 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
32820 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
32830 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
32840 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
32850 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
32860 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
32870 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
32880 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
32890 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
328a0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
328b0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
328c0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
328d0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
328e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
328f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32900 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
32910 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
32920 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
32930 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
32940 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
32950 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32960 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
32970 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
32980 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
32990 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
329a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
329b0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
329c0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
329d0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
329e0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
329f0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
32a00 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
32a10 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
32a20 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
32a30 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
32a40 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
32a50 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
32a60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
32a70 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
32a80 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
32a90 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
32aa0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
32ab0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
32ac0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
32ad0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
32ae0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
32af0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
32b00 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
32b10 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
32b20 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
32b30 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
32b40 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
32b50 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
32b60 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
32b70 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
32b80 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
32b90 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
32ba0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
32bb0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
32bc0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
32bd0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
32be0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
32bf0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
32c00 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
32c10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
32c20 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
32c30 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
32c40 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
32c50 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
32c60 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
32c70 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
32c80 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
32c90 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
32ca0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
32cb0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
32cc0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
32cd0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
32ce0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
32cf0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
32d00 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
32d10 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
32d20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
32d30 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
32d40 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
32d50 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
32d60 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
32d70 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
32d80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
32d90 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
32da0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
32db0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
32dc0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
32dd0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
32de0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
32df0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
32e00 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
32e10 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
32e20 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
32e30 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
32e40 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
32e50 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
32e60 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
32e70 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
32e80 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
32e90 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
32ea0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
32eb0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
32ec0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
32ed0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
32ee0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
32ef0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
32f00 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
32f10 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
32f20 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
32f30 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
32f40 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
32f50 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
32f60 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
32f70 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
32f80 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
32f90 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
32fa0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
32fb0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
32fc0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
32fd0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
32fe0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
32ff0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
33000 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
33010 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
33020 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
33030 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
33040 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
33050 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
33060 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
33070 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
33080 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
33090 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
330a0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
330b0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
330c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
330d0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
330e0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
330f0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
33100 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
33110 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
33120 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
33130 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
33140 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33150 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
33160 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
33170 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
33180 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
33190 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
331a0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
331b0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
331c0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
331d0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
331e0 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
331f0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
33200 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
33210 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
33220 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
33230 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
33240 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33250 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
33260 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
33270 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
33280 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
33290 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
332a0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
332b0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
332c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
332d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
332e0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
332f0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
33300 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
33310 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
33320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
33330 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
33340 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
33350 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
33360 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
33370 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
33380 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
33390 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
333a0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
333b0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
333c0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
333d0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
333e0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  mt.**.** ^(The f
333f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
33400 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
33410 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
33420 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
33430 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
33440 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
33450 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
33460 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
33470 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
33480 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
33490 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
334a0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
334b0 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
334c0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
334d0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
334e0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
334f0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
33500 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
33510 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
33520 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
33530 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
33540 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
33550 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
33560 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
33570 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
33580 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
33590 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
335a0 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
335b0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
335c0 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
335d0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
335e0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
335f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
33600 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
33610 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
33620 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
33630 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
33640 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
33650 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
33660 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
33670 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
33680 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
33690 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
336a0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
336b0 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
336c0 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
336d0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
336e0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
336f0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
33700 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
33710 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
33720 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
33730 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
33740 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
33750 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
33760 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
33770 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
33780 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
33790 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
337a0 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
337b0 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
337c0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
337d0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
337e0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
337f0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
33800 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
33810 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
33820 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
33830 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
33840 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
33850 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
33860 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
33870 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
33880 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
33890 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
338a0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
338b0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
338c0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
338d0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
338e0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
338f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
33900 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41  te3_stmt.**.** A
33910 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
33920 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
33930 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
33940 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73  ing any of.** [s
33950 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
33960 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
33970 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
33980 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33990 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  _v2()],.** or [s
339a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
339b0 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v3()] or one of
339c0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
339d0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
339e0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
339f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33a00 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
33a10 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
33a20 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
33a30 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
33a40 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
33a50 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
33a60 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
33a70 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
33a80 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
33a90 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
33aa0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
33ab0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
33ac0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
33ad0 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65   newer "vX" inte
33ae0 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  rfaces.** [sqlit
33af0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
33b00 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
33b10 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
33b20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
33b30 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
33b40 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
33b50 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
33b60 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
33b70 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
33b80 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
33b90 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
33ba0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
33bb0 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74  .** new "vX" int
33bc0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
33bd0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
33be0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
33bf0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
33c00 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
33c10 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
33c20 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
33c30 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
33c40 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
33c50 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
33c60 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
33c70 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
33c80 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
33c90 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
33ca0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
33cb0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
33cc0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
33cd0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
33ce0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
33cf0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
33d00 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
33d10 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
33d20 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
33d30 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
33d40 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
33d50 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
33d60 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
33d70 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
33d80 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
33d90 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
33da0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
33db0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
33dc0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
33dd0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
33de0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
33df0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
33e00 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
33e10 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
33e20 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
33e30 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
33e40 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
33e50 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
33e60 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
33e70 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
33e80 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
33e90 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
33ea0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
33eb0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
33ec0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
33ed0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
33ee0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
33ef0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
33f00 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
33f10 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
33f20 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
33f30 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
33f40 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
33f50 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
33f60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33f70 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
33f80 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
33f90 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
33fa0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
33fb0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
33fc0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
33fd0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
33fe0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
33ff0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
34000 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
34010 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
34020 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
34030 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
34040 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
34050 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
34060 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
34070 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
34080 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
34090 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
340a0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
340b0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
340c0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
340d0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
340e0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
340f0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
34100 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
34110 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
34120 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
34130 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
34140 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
34150 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
34160 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
34170 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
34180 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
34190 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
341a0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
341b0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
341c0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
341d0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
341e0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
341f0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
34200 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
34210 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
34220 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
34230 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
34240 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
34250 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
34260 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
34270 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
34280 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
34290 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
342a0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
342b0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
342c0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
342d0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
342e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
342f0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
34300 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
34310 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
34320 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
34330 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
34340 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
34350 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
34360 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34370 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
34380 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
34390 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
343a0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
343b0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
343c0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
343d0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
343e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
343f0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
34400 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
34410 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
34420 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34430 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
34440 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
34450 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
34460 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
34470 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
34480 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
34490 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
344a0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
344b0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
344c0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
344d0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
344e0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
344f0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
34500 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
34510 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
34520 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
34530 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
34540 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
34550 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
34560 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
34570 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34580 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
34590 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
345a0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
345b0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
345c0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
345d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
345e0 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72    But after [ver
345f0 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28  sion 3.6.23.1] (
34600 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31  [dateof:3.6.23.1
34610 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ],.** sqlite3_st
34620 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
34630 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
34640 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
34650 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
34660 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
34670 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
34680 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
34690 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
346a0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
346b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
346c0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
346d0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
346e0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
346f0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
34700 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
34710 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
34720 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
34730 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
34740 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
34750 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
34760 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
34770 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
34780 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
34790 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
347a0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
347b0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
347c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
347d0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
347e0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
347f0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
34800 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
34810 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
34820 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
34830 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
34840 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
34850 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
34860 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
34870 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
34880 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
34890 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
348a0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
348b0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
348c0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
348d0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
348e0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
348f0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
34900 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
34910 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
34920 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
34930 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
34940 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
34950 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
34960 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
34970 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  nts.** using [sq
34980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
34990 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
349a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
349b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
349c0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
349d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
349e0 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64  16_v3()] instead
349f0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
34a00 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
34a10 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
34a20 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
34a30 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
34a40 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
34a50 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
34a60 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
34a70 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
34a80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
34a90 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
34aa0 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20  "vX" interfaces 
34ab0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
34ac0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
34ad0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
34ae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
34af0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34b00 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
34b10 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
34b20 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
34b30 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
34b40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
34b50 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
34b60 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
34b70 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
34b80 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
34b90 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
34ba0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
34bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34bc0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
34bd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
34be0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
34bf0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
34c00 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
34c10 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
34c20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
34c30 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
34c40 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
34c50 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
34c60 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
34c70 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
34c80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
34c90 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
34ca0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
34cb0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
34cc0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
34cd0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
34ce0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
34cf0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
34d00 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
34d10 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
34d20 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
34d30 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
34d40 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
34d50 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
34d60 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
34d70 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
34d80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
34d90 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
34da0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
34db0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
34dc0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
34dd0 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
34de0 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
34df0 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
34e00 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
34e10 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
34e20 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
34e30 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
34e40 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
34e50 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
34e60 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
34e70 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  mn_count()].*/.S
34e80 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34e90 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
34ea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
34eb0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
34ec0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
34ed0 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
34ee0 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
34ef0 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
34f00 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
34f10 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
34f20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
34f30 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
34f40 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
34f50 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
34f60 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
34f70 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
34f80 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
34f90 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
34fa0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
34fb0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
34fc0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
34fd0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
34fe0 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
34ff0 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
35000 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
35010 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
35020 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
35030 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
35040 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
35050 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
35060 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
35070 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
35080 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
35090 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
350a0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
350b0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
350c0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
350d0 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
350e0 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
350f0 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
35100 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
35110 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
35120 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
35130 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
35140 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
35150 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
35160 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
35170 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
35180 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
35190 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
351a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
351b0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
351c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
351d0 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
351e0 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
351f0 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
35200 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
35210 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
35220 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53  _stmt.**.** <b>S
35230 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c  ummary:</b>.** <
35240 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c  blockquote><tabl
35250 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70  e border=0 cellp
35260 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61  adding=0 cellspa
35270 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c  cing=0>.** <tr><
35280 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
35290 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64  lumn_blob</b><td
352a0 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20  >&rarr;<td>BLOB 
352b0 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
352c0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
352d0 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74  umn_double</b><t
352e0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c  d>&rarr;<td>REAL
352f0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
35300 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
35310 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e  lumn_int</b><td>
35320 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74  &rarr;<td>32-bit
35330 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a   INTEGER result.
35340 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
35350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
35360 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  64</b><td>&rarr;
35370 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47  <td>64-bit INTEG
35380 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
35390 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
353a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c  column_text</b><
353b0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
353c0 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a  -8 TEXT result.*
353d0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
353e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
353f0 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  16</b><td>&rarr;
35400 3c 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20  <td>UTF-16 TEXT 
35410 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
35420 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
35430 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64  umn_value</b><td
35440 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72  >&rarr;<td>The r
35450 65 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20  esult as an .** 
35460 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75  [sqlite3_value|u
35470 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35480 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35490 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62  ..** <tr><td>&nb
354a0 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  sp;<td>&nbsp;<td
354b0 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c  >&nbsp;.** <tr><
354c0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
354d0 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74  lumn_bytes</b><t
354e0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65  d>&rarr;<td>Size
354f0 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72   of a BLOB.** or
35500 20 61 20 55 54 46 2d 38 20 54 45 58 54 20 72 65   a UTF-8 TEXT re
35510 73 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a  sult in bytes.**
35520 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
35530 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35540 31 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f  16&nbsp;&nbsp;</
35550 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b  b>.** <td>&rarr;
35560 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e  &nbsp;&nbsp;<td>
35570 53 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a  Size of UTF-16.*
35580 2a 20 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a  * TEXT in bytes.
35590 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
355a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
355b0 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
355c0 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61  td>Default.** da
355d0 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65  tatype of the re
355e0 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  sult.** </table>
355f0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
35600 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c  .** <b>Details:<
35610 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  /b>.**.** ^These
35620 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
35630 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
35640 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
35650 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
35660 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
35670 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
35680 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
35690 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
356a0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
356b0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
356c0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
356d0 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
356e0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
356f0 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
35700 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
35710 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
35720 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
35730 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
35740 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
35750 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
35760 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
35770 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
35780 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
35790 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
357a0 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
357b0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
357c0 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
357d0 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
357e0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
357f0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
35800 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
35810 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
35820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
35830 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
35840 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
35850 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
35860 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
35870 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
35880 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
35890 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
358a0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
358b0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
358c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
358d0 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
358e0 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
358f0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
35900 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
35910 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
35920 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
35930 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
35940 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
35950 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
35960 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
35970 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
35980 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
35990 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
359a0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
359b0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
359c0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
359d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
359e0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
359f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
35a00 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
35a10 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
35a20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
35a30 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
35a40 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
35a50 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
35a60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
35a70 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
35a80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
35a90 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
35aa0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
35ab0 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
35ac0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
35ad0 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
35ae0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
35af0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
35b00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
35b10 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 73  t six interfaces
35b20 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65   (_blob, _double
35b30 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20  , _int, _int64, 
35b40 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74  _text, and _text
35b50 31 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75  16).** each retu
35b60 72 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  rn the value of 
35b70 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
35b80 69 6e 20 61 20 73 70 65 63 69 66 69 63 20 64 61  in a specific da
35b90 74 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a  ta format.  If.*
35ba0 2a 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  * the result col
35bb0 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69  umn is not initi
35bc0 61 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75  ally in the requ
35bd0 65 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f  ested format (fo
35be0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66  r example,.** if
35bf0 20 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72   the query retur
35c00 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75  ns an integer bu
35c10 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  t the sqlite3_co
35c20 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65  lumn_text() inte
35c30 72 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64  rface.** is used
35c40 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20   to extract the 
35c50 76 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61  value) then an a
35c60 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
35c70 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
35c80 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ormed..**.** ^Th
35c90 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
35ca0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
35cb0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
35cc0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
35cd0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
35ce0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
35cf0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
35d00 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
35d10 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
35d20 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
35d30 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
35d40 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
35d50 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
35d60 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
35d70 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
35d80 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65  NULL]..** The re
35d90 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71  turn value of sq
35da0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
35db0 65 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20  e() can be used 
35dc0 74 6f 20 64 65 63 69 64 65 20 77 68 69 63 68 0a  to decide which.
35dd0 2a 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  ** of the first 
35de0 73 69 78 20 69 6e 74 65 72 66 61 63 65 20 73 68  six interface sh
35df0 6f 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20  ould be used to 
35e00 65 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75  extract the colu
35e10 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65  mn value..** The
35e20 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
35e30 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
35e40 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
35e50 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
35e60 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74  o.** automatic t
35e70 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
35e80 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f  have occurred fo
35e90 72 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71  r the value in q
35ea0 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66  uestion.  .** Af
35eb0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
35ec0 72 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c  rsion, the resul
35ed0 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c  t of calling sql
35ee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
35ef0 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ().** is undefin
35f00 65 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c  ed, though harml
35f10 65 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ess.  Future.** 
35f20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
35f30 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
35f40 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
35f50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
35f60 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
35f70 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
35f80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
35f90 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
35fa0 42 20 6f 72 20 61 20 54 45 58 54 20 73 74 72 69  B or a TEXT stri
35fb0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ng, then the sql
35fc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35fd0 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  s().** or sqlite
35fe0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35ff0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 63 61  () interfaces ca
36000 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74  n be used to det
36010 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a  ermine the size.
36020 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20  ** of that BLOB 
36030 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  or string..**.**
36040 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
36050 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
36060 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
36070 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
36080 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
36090 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
360a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
360b0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
360c0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
360d0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
360e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
360f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
36100 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
36110 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
36120 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
36130 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
36140 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
36150 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
36160 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
36170 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
36180 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36190 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
361a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
361b0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
361c0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
361d0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
361e0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
361f0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
36200 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
36210 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
36220 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
36230 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36240 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
36250 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
36260 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
36270 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
36280 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
36290 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
362a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
362b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
362c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
362d0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
362e0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
362f0 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
36300 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
36310 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
36320 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
36330 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
36340 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
36350 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
36360 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
36370 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
36380 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
36390 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
363a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
363b0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
363c0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
363d0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
363e0 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
363f0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
36400 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
36410 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
36420 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
36430 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
36440 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
36450 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
36460 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
36470 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
36480 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
36490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
364a0 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
364b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
364c0 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
364d0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
364e0 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
364f0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
36500 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
36510 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
36520 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
36530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
36540 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
36550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36560 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
36570 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
36580 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
36590 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
365a0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
365b0 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
365c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
365d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
365e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
365f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
36600 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
36610 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
36620 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
36630 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
36640 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
36650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36660 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
36670 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
36680 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
36690 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f  ** <b>Warning:</
366a0 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  b> ^The object r
366b0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
366c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
366d0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
366e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
366f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
36700 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65    In a multithre
36710 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  aded environment
36720 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63  ,.** an unprotec
36730 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36740 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c  e object may onl
36750 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79  y be used safely
36760 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
36770 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
36780 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
36790 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
367a0 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
367b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
367c0 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
367d0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
367e0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
367f0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
36800 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
36810 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
36820 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
36830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36840 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
36850 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
36860 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
36870 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
36880 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e  he behavior is n
36890 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a  ot threadsafe..*
368a0 2a 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c  * Hence, the sql
368b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
368c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  e() interface.**
368d0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c   is normally onl
368e0 79 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20  y useful within 
368f0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
36900 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69  on of .** [appli
36910 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
36920 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
36930 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
36940 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a  ], not within.**
36950 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69   top-level appli
36960 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a  cation code..**.
36970 2a 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f 75  ** The these rou
36980 74 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70  tines may attemp
36990 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
369a0 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
369b0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72   result..** ^For
369c0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
369d0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
369e0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
369f0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
36a00 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
36a10 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
36a20 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
36a30 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
36a40 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
36a50 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
36a60 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
36a70 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
36a80 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
36a90 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
36aa0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
36ab0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
36ac0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
36ad0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
36ae0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
36af0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
36b00 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
36b10 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
36b20 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
36b30 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
36b40 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
36b50 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
36b60 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
36b70 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
36b80 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
36b90 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
36ba0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
36bb0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
36bc0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
36bd0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
36be0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
36bf0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
36c00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
36c10 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
36c20 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
36c30 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
36c40 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
36c50 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
36c60 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
36c70 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
36c80 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
36c90 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
36ca0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
36cb0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
36cc0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
36cd0 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
36ce0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
36cf0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
36d00 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
36d10 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
36d20 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
36d30 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
36d40 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
36d50 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
36d60 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
36d70 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
36d80 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
36d90 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
36da0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
36db0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
36dc0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
36dd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
36de0 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
36df0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
36e00 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
36e10 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
36e20 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
36e30 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
36e40 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
36e50 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
36e60 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
36e70 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
36e80 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
36e90 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
36ea0 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
36eb0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
36ec0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
36ed0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
36ee0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
36ef0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
36f00 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
36f10 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  te>)^.**.** Note
36f20 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
36f30 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
36f40 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
36f50 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
36f60 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
36f70 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
36f80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36f90 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
36fa0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
36fb0 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
36fc0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
36fd0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
36fe0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
36ff0 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
37000 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
37010 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
37020 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
37030 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
37040 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
37050 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
37060 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
37070 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
37080 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
37090 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
370a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
370b0 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
370c0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
370d0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
370e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
370f0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
37100 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
37110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37120 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
37130 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
37140 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
37150 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
37160 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
37170 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
37180 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
37190 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
371a0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
371b0 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
371c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
371d0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
371e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
371f0 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
37200 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
37210 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
37220 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
37230 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
37240 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
37250 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
37260 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
37270 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
37280 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
37290 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
372a0 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
372b0 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
372c0 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
372d0 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
372e0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
372f0 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
37300 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
37310 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
37320 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
37330 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
37340 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
37350 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
37360 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
37370 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
37380 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
37390 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
373a0 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
373b0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
373c0 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69   The safest poli
373d0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
373e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
373f0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
37400 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
37410 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
37420 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
37430 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
37440 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
37450 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
37460 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
37470 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
37480 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
37490 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
374a0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
374b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
374c0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
374d0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
374e0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
374f0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
37500 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
37510 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
37520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37530 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
37540 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
37550 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
37560 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
37570 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
37580 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
37590 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
375a0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
375b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
375c0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
375d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
375e0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
375f0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
37600 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
37610 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
37620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
37630 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
37640 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
37650 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
37660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37670 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
37680 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
37690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
376a0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
376b0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
376c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
376d0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
376e0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
376f0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
37700 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
37710 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
37720 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
37730 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
37740 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
37750 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
37760 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
37770 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
37780 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
37790 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
377a0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
377b0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
377c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
377d0 6f 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70  o not pass the p
377e0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
377f0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
37800 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
37810 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
37820 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
37830 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
37840 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
37850 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 69  As long as the i
37860 6e 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  nput parameters 
37870 61 72 65 20 63 6f 72 72 65 63 74 2c 20 74 68 65  are correct, the
37880 73 65 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  se routines will
37890 20 6f 6e 6c 79 0a 2a 2a 20 66 61 69 6c 20 69 66   only.** fail if
378a0 20 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72   an out-of-memor
378b0 79 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  y error occurs d
378c0 75 72 69 6e 67 20 61 20 66 6f 72 6d 61 74 20 63  uring a format c
378d0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 4f 6e  onversion..** On
378e0 6c 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ly the following
378f0 20 73 75 62 73 65 74 20 6f 66 20 69 6e 74 65 72   subset of inter
37900 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63  faces are subjec
37910 74 20 74 6f 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  t to out-of-memo
37920 72 79 0a 2a 2a 20 65 72 72 6f 72 73 3a 0a 2a 2a  ry.** errors:.**
37930 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
37940 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37950 62 6c 6f 62 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73  blob().** <li> s
37960 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37970 78 74 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  xt().** <li> sql
37980 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
37990 31 36 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  16().** <li> sql
379a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
379b0 73 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  s().** <li> sqli
379c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
379d0 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  16().** </ul>.**
379e0 0a 2a 2a 20 49 66 20 61 6e 20 6f 75 74 2d 6f 66  .** If an out-of
379f0 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72 20 6f 63  -memory error oc
37a00 63 75 72 73 2c 20 74 68 65 6e 20 74 68 65 20 72  curs, then the r
37a10 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
37a20 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e   these.** routin
37a30 65 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  es is the same a
37a40 73 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  s if the column 
37a50 68 61 64 20 63 6f 6e 74 61 69 6e 65 64 20 61 6e  had contained an
37a60 20 53 51 4c 20 4e 55 4c 4c 20 76 61 6c 75 65 2e   SQL NULL value.
37a70 0a 2a 2a 20 56 61 6c 69 64 20 53 51 4c 20 4e 55  .** Valid SQL NU
37a80 4c 4c 20 72 65 74 75 72 6e 73 20 63 61 6e 20 62  LL returns can b
37a90 65 20 64 69 73 74 69 6e 67 75 69 73 68 65 64 20  e distinguished 
37aa0 66 72 6f 6d 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  from out-of-memo
37ab0 72 79 20 65 72 72 6f 72 73 0a 2a 2a 20 62 79 20  ry errors.** by 
37ac0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 5b 73 71  invoking the [sq
37ad0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
37ae0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
37af0 65 72 20 74 68 65 20 73 75 73 70 65 63 74 0a 2a  er the suspect.*
37b00 2a 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  * return value i
37b10 73 20 6f 62 74 61 69 6e 65 64 20 61 6e 64 20 62  s obtained and b
37b20 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 6f 74 68  efore any.** oth
37b30 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
37b40 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ace is called on
37b50 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
37b60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
37b70 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
37b80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
37b90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
37ba0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
37bb0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
37bc0 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  API double sqlit
37bd0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
37be0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
37bf0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
37c00 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
37c10 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
37c20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
37c30 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
37c40 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
37c50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
37c60 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
37c70 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
37c80 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
37c90 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
37ca0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37cb0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
37cc0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
37cd0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
37ce0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
37cf0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
37d00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
37d10 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
37d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
37d30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
37d40 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
37d50 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
37d60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
37d70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37d80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
37d90 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
37da0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
37db0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
37dc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
37dd0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
37de0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
37df0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
37e00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
37e10 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
37e20 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
37e30 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
37e40 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
37e50 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
37e60 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
37e70 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
37e80 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
37e90 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
37ea0 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
37eb0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
37ec0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
37ed0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
37ee0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
37ef0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
37f00 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
37f10 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
37f20 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
37f30 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
37f40 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
37f50 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
37f60 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
37f70 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
37f80 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
37f90 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
37fa0 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
37fb0 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
37fc0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
37fd0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
37fe0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
37ff0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
38000 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
38010 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
38020 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
38030 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
38040 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
38050 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
38060 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
38070 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
38080 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
38090 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
380a0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
380b0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
380c0 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
380d0 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
380e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
380f0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
38100 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
38110 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
38120 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
38130 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
38140 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
38150 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
38160 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
38170 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
38180 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
38190 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
381a0 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
381b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
381c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
381d0 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
381e0 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
381f0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
38200 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
38210 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
38220 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
38230 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
38240 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
38250 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
38260 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
38270 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
38280 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
38290 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
382a0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
382b0 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
382c0 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
382d0 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
382e0 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
382f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
38300 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
38310 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
38320 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
38330 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
38340 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
38350 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d  ment Object.** M
38360 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
38370 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  tmt.**.** The sq
38380 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
38390 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
383a0 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
383b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
383c0 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
383d0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
383e0 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
383f0 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
38400 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
38410 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
38420 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
38430 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
38440 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
38450 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
38460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
38470 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
38480 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
38490 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
384a0 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
384b0 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
384c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
384d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
384e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
384f0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
38500 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
38510 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
38520 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
38530 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
38540 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
38550 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
38560 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
38570 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
38580 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
38590 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
385a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
385b0 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
385c0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
385d0 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
385e0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
385f0 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
38600 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
38610 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
38620 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
38630 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
38640 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
38650 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
38660 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
38670 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
38680 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
38690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
386a0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
386b0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
386c0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code