/ Hex Artifact Content
Login

Artifact d19c873a17c2effd4417f687fad942b6cc0ab0c64535f669cc2f22a5b05db23b:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6c 73 65 0a 23 20 64  nt N);.#else.# d
1e00: 65 66 69 6e 65 20 73 71 6c 69 74 65 33 5f 63 6f  efine sqlite3_co
1e10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1e20: 28 58 29 20 30 0a 23 20 64 65 66 69 6e 65 20 73  (X) 0.# define s
1e30: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1e40: 74 69 6f 6e 5f 67 65 74 28 58 29 20 20 28 28 76  tion_get(X)  ((v
1e50: 6f 69 64 2a 29 30 29 0a 23 65 6e 64 69 66 0a 0a  oid*)0).#endif..
1e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e70: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1e80: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1e90: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1eb0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ec0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1ed0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1ee0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1ef0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1f00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1f10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1f20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1f50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1f60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1f70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1f80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1f90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1fa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1fb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1fc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1fd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1fe0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1ff0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
2000: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
2010: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2020: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
2030: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
2040: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
2050: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
2060: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
2070: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
2080: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
2090: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
20a0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
20b0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
20c0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
20d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
20e0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
20f0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
2100: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
2110: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
2120: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
2130: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
2140: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
2150: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
2160: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
2170: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
2180: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
2190: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
21a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
21b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
21c0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
21d0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
21e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
21f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
2200: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
2210: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
2220: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2230: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
2240: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
2250: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2260: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
2270: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
2280: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2290: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
22a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
22b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
22c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
22d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
22e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
22f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2300: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2310: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2320: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2330: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2340: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2350: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2360: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2370: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2380: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2390: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
23a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
23b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
23c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
23d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
23e0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
23f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2400: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
2410: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
2420: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
2430: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2440: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
2450: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
2460: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
2470: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
2480: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
2490: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
24a0: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
24b0: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
24c0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
24d0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
24e0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
24f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2500: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
2510: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
2520: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
2530: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2550: 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ation..*/.int sq
2560: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2570: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
2580: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2590: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
25a0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
25b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
25c0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
25d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
25e0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
25f0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2600: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2610: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2620: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2630: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
2640: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
2650: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
2660: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
2670: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
2680: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
2690: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
26a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
26b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
26c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
26d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
26e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
26f0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2710: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2720: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2730: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
2740: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2750: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
2760: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
2770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2790: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27a0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
27b0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
27c0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
27d0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
27e0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
27f0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2800: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2810: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2820: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2830: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
2840: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
2850: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
2860: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
2870: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
2880: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
2890: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
28a0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
28b0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
28c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
28d0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
28e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
28f0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2900: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2920: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2930: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
2940: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
2950: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
2960: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
2970: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2980: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
2990: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
29a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
29b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
29c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
29d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
29e0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
29f0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2a00: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2a10: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2a20: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2a30: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
2a40: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2a50: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
2a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2a70: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2a80: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
2a90: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2aa0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2ab0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2ac0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2ad0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2ae0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2af0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2b00: 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54  4;.# ifdef SQLIT
2b10: 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  E_UINT64_TYPE.  
2b20: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2b30: 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  _UINT64_TYPE sql
2b40: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c  ite_uint64;.# el
2b50: 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66  se  .    typedef
2b60: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2b70: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2b80: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64  te_uint64;.# end
2b90: 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  if.#elif defined
2ba0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
2bb0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
2bc0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
2bd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2be0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2bf0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2c00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2c10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2c20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2c50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2c60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2c70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2c90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2ca0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2cb0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2cc0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2cd0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ce0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2cf0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2d00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2d10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2d20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2d30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2d40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2d50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2d70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2d80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2d90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2da0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2db0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2dd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2df0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2e00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2e10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2e20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2e30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2e40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2e50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2e60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2e70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2e80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2e90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ea0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2eb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2ec0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ed0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ef0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2f00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2f10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2f20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2f30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2f40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2f50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2f60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2f90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2fa0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2fd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2fe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2ff0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
3000: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
3010: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
3020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3030: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
3040: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
3050: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
3060: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
3070: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
3080: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30a0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
30b0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
30c0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
30d0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
30e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
30f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
3100: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
3110: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
3120: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
3130: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
3140: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
3150: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
3160: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
3170: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
3180: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
3190: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31b0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
31c0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
31d0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
31e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
31f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3200: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3210: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3220: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3230: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3240: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3250: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3260: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3280: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3290: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
32a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
32c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
32f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3300: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3310: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3320: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3340: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3350: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3360: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3370: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3380: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3390: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
33a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
33b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
33c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
33d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
33e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
33f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3400: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3410: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3420: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3440: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3450: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3460: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3470: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3480: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
34a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
34c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
34d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
34e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
34f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3500: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3510: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3520: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3530: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3540: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3550: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3560: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3570: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3580: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3590: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
35a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
35b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
35c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
35e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
35f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3600: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3610: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3620: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3630: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3640: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3650: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3660: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3670: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3680: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3690: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
36a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
36b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
36c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
36d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
36e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3700: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3710: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3720: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3730: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3740: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3750: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3760: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3790: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
37a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
37c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
37d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
37e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
37f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3800: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3810: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3820: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3830: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3840: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3850: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3860: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3870: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3880: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3890: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
38a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
38b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
38c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
38e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
38f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3900: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3910: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3920: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3930: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3940: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3950: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3960: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3970: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3980: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3990: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
39a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
39b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
39c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
39d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
39e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
39f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3a00: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3a10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3a40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3a50: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3a60: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3a70: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3a80: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3a90: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3aa0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3ab0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3ac0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3ad0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3ae0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3af0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3b00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3b10: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3b20: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3b30: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3b40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b60: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3b70: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3b90: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3ba0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3bb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3bc0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3bd0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bf0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3c00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3c20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3c30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3c40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3c50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3c60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3c70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3c90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3ca0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3cb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3cc0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3cd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3cf0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3d00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3d10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3d20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3d30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3d40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3d50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3d60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3d70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3d80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3d90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3da0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3db0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3dc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3dd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3de0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3df0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3e00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3e10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3e20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3e30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3e40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3e50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3e70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3e80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3e90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ea0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3eb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3ec0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3ed0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ee0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3ef0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3f00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3f10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3f20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3f30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3f40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3f50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3f60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3f70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3f80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fa0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3fb0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3fc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3fd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3fe0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ff0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
4000: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
4010: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
4020: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
4030: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
4040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
4050: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
4060: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
4070: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
4080: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
4090: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
40a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40b0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
40c0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
40d0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
40e0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
40f0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
4100: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
4110: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
4120: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
4130: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
4140: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
4150: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
4160: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
4170: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
4180: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
4190: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
41b0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
41c0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
41d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
41e0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
41f0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4200: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4210: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4220: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4230: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4250: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4260: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4270: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4280: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4290: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
42a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
42b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
42c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
42d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
42e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
42f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4300: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4310: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4320: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4330: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4340: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4350: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4360: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4370: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4390: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
43a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
43b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
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 2f 2a 20 53 51 4c 20 74          /* SQL t
43e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
43f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4410: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4420: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4430: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4460: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4470: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4480: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4490: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
44a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
44c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
44d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
44e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
44f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4520: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4530: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4540: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4550: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4560: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4570: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4580: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4590: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
45a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
45b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
45c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
45d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
45e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
45f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4600: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4620: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4630: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4640: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4650: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4670: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4680: 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f   /* Generic erro
4690: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
46a0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
46b0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
46c0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
46d0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
46f0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4700: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4710: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4720: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4730: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4740: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4750: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4770: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4780: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4790: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
47a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47b0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
47c0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
47d0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
47e0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4800: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4810: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4820: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4830: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4840: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4850: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4860: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4880: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4890: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
48a0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
48b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48d0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
48e0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
48f0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4900: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4920: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4930: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4940: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4950: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4960: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4970: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4980: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4990: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
49a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
49b0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
49c0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
49d0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
49e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
49f0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4a00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4a10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4a20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4a30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4a50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4a60: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4a70: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4a90: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4aa0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20  /* Internal use 
4ab0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
4ac0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4ad0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4ae0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4af0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4b10: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4b20: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4b30: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4b40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4b60: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4b70: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4b80: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4ba0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4bb0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4bc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4bd0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4be0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4bf0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c10: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4c20: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4c30: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4c40: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4c60: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4c70: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4c80: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4c90: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ca0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74       24   /* Not
4cb0: 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
4cc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
4cd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
4ce0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4cf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
4d00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
4d20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
4d30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
4d40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
4d50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4d60: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
4d70: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
4d80: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
4d90: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
4db0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
4dc0: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
4dd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4df0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
4e00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4e10: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
4e20: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
4e30: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
4e40: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
4e50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4e60: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
4e70: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
4e80: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4e90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4ea0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
4eb0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4ec0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
4ee0: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e  itions}.**.** In
4ef0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4f00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4f10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4f20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30  return one of 30
4f30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73   integer.** [res
4f40: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4f50: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4f60: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4f70: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4f80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f90: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4fa0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4fb0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4fc0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4fd0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4fe0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4ff0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
5000: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
5010: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
5020: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
5030: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
5040: 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e  3.3.8 [dateof:3.
5050: 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65  3.8].** and late
5060: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
5070: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
5080: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
5090: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
50a0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
50b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
50c0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
50d0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
50e0: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
50f0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
5100: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
5110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
5120: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
5130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
5140: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
5150: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
5160: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
5170: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
5180: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
5190: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
51a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
51b0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
51c0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
51d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53  SQLITE_ERROR_MIS
51e0: 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28  SING_COLLSEQ   (
51f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28  SQLITE_ERROR | (
5200: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5210: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52  QLITE_ERROR_RETR
5220: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  Y             (S
5230: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32  QLITE_ERROR | (2
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5250: 4c 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53  LITE_ERROR_SNAPS
5260: 48 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51  HOT          (SQ
5270: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c  LITE_ERROR | (3<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
52c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
52d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
52e0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
52f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5300: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5310: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5320: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5330: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5350: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5370: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
53a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
53c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
53d0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
53e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
53f0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5410: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5420: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5430: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5450: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5470: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5490: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54b0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
55e0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
55f0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56d0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56f0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5710: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5720: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5730: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5750: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5760: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5770: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5780: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5790: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
57a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57b0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
57c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57d0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
57e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57f0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5810: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5820: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5830: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5840: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5850: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5860: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5870: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5890: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
58a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58b0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58d0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58f0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5910: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5920: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5930: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5950: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5960: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5970: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5990: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59b0: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
59d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59f0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5a10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5a30: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a50: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a70: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5a90: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5ab0: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<8)).#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ad0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5af0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5b10: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5b30: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5b40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b50: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5b60: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5b70: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5bc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5be0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5bf0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5c20: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5c30: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5c40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5c60: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5c70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5c80: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5c90: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5cb0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5cf0: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5d00: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5d10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5d20: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5d30: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5d40: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5d50: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5d70: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5d80: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5d90: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5db0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5dd0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5df0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5e20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5e40: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5e50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5e60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5e80: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5e90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5ea0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5eb0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5ec0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5ed0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5ee0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ef0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f00: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5f10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5f30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5f40: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5f50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5f60: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5f80: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5f90: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5fc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5fd0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5ff0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6000: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6010: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6030: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
6040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6050: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
6060: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6070: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6090: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
60a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
60b0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
60c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
60d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
60e0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6110: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6120: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6140: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
6150: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6160: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
6170: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6180: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61a0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
61b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
61c0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61e0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
61f0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6200: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6220: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
6240: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
6260: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
6270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
6280: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
62a0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
62b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
62c0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
62d0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
62e0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
62f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6300: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6310: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6320: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6330: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
6340: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
6350: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
6360: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
6370: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
6380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6390: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
63a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6410: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6420: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
6460: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6470: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
64b0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
64c0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6500: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6520: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6530: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
6540: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
6590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65b0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
65c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65d0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
65e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6620: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6660: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
6670: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6680: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
6690: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
66a0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
66b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
66d0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
66e0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
66f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6700: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6710: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6720: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6740: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6750: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
6760: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6770: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6780: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6790: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
67a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
67d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6820: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
6870: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
6880: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6890: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
68b0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
68c0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
68d0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
68e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6920: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6930: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
6940: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6950: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
6960: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
6970: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
6980: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
6990: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
69a0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
69b0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
69c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
69d0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
69e0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
69f0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6a00: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6a10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6a20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6a30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6a40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6a50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
6a60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
6a70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6a80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
6a90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6ab0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6ac0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6ad0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6ae0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6b10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6b20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6b30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6b40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6b50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6b60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6b70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6b80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6b90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6ba0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6bb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6bc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6bd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6be0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6bf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6c00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6c10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6c20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6c30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6c40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6c50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6c60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6c70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6c80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6c90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6ca0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6cb0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6cc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6cd0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6ce0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6cf0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6d00: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6d10: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6d20: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6d30: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6d40: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6d50: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6d60: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6d70: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6d80: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6d90: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6da0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6db0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6dc0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6dd0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6de0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6df0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6e00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6e10: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6e20: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6e30: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6e40: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6e50: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6e60: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6e70: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6e80: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6e90: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6ea0: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6eb0: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6ec0: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6ed0: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6ee0: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6ef0: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6f10: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6f20: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6f30: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6f40: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6f50: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6f60: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6f70: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6f80: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6f90: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6fa0: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6fc0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6fd0: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6fe0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6ff0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
7000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7010: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
7020: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7030: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
7040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7050: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
7060: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
7070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7080: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
7090: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
70a0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
70b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70c0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
70d0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
70e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
70f0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
7100: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7110: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7120: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7140: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
7150: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7160: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
7170: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
7180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7190: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
71a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
71b0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
71c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
71d0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
71e0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
71f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7200: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7210: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7220: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7230: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7240: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
7250: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
7260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7270: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
7280: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
7290: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
72a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
72b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
72c0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
72d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
72e0: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
72f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
7300: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7310: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7320: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7330: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
7340: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
7350: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
7360: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
7370: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
7380: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
7390: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
73a0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
73b0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
73c0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
73d0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
73e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
73f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7400: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
7410: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7420: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7430: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
7440: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
7450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7460: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
7470: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7480: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
7490: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
74a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
74b0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
74c0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
74d0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
74e0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
74f0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
7500: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
7510: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7520: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7530: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
7540: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
7550: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
7560: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7570: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
7580: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
7590: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
75a0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
75b0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
75c0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
75d0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
75e0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
75f0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
7600: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
7610: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7620: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7630: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7640: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
7650: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
7660: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
7670: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
7680: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
7690: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
76a0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
76b0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
76c0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
76d0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
76e0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
76f0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7700: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7710: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7720: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7730: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7740: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7750: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7760: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7770: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
7780: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7790: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
77a0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
77b0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
77c0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
77d0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
77e0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
77f0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7800: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7810: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7820: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7830: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7840: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7850: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7860: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7870: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
7880: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
7890: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
78a0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
78b0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
78c0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
78d0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
78e0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
78f0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7900: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7910: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7920: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7930: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7940: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7950: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7960: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7970: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7980: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
7990: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
79a0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
79b0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
79c0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
79d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
79e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
79f0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7a00: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7a10: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7a20: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7a30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7a40: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7a50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7a60: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7a70: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
7a80: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
7a90: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7aa0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7ab0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
7ac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
7ad0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7ae0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7af0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7b10: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7b20: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7b30: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7b40: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7b50: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7b60: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7b70: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7b80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7b90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7ba0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7bb0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7bc0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7bd0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7be0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7bf0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7c00: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7c10: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7c20: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7c30: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7c40: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7c50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7c60: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7c70: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7c80: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7c90: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7ca0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7cb0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7cc0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7cd0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7ce0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7cf0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7d00: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7d10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7d20: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7d30: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7d40: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7d50: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7d60: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7d70: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7d80: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7d90: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7da0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7db0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7dc0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7dd0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7de0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7df0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7e00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7e10: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7e20: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7e30: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7e40: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7e50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7e60: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7e70: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7e80: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7e90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7ea0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7eb0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7ec0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7ed0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7ee0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7ef0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7f00: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7f10: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7f20: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7f30: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7f40: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7f50: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7f60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7f70: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7f80: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7f90: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7fa0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7fb0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7fc0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7fd0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7fe0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7ff0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
8000: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
8010: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
8020: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
8030: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
8040: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
8050: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
8060: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
8070: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
8080: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
8090: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
80a0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
80b0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
80c0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
80d0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
80e0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
80f0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
8100: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
8110: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8120: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8130: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
8140: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
8150: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8160: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
8170: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8180: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
8190: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
81a0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
81b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
81c0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
81d0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
81e0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
81f0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
8200: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
8210: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8220: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8230: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
8240: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
8250: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
8260: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
8270: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
8280: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
8290: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
82a0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
82b0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
82c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
82d0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
82e0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
82f0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
8300: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
8310: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8320: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8330: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
8340: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
8350: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
8360: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8370: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
8380: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
8390: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
83a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
83b0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
83c0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
83d0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
83e0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
83f0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
8400: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
8410: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8420: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8430: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
8440: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
8450: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
8460: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
8470: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
8480: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
8490: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
84a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
84b0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
84c0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
84d0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
84e0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
84f0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
8500: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
8510: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8520: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8530: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
8540: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
8550: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
8560: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
8570: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
8580: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
8590: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
85a0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
85b0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
85c0: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
85d0: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
85e0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
85f0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
8600: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
8610: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8620: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8630: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8640: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
8650: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
8660: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
8670: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
8680: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8690: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
86a0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
86b0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
86c0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
86d0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
86e0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
86f0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
8700: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
8710: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8720: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8730: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
8740: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
8750: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
8760: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
8770: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
8780: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
8790: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
87a0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
87b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
87c0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
87d0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
87e0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
87f0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
8800: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8810: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8820: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8830: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8840: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8850: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
8870: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
8880: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8890: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
88a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88b0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88d0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
88e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88f0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8910: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8920: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8930: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
8940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8950: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
8960: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8970: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
8980: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8990: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
89a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
89b0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
89c0: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
89d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
89e0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
89f0: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
8a00: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8a10: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8a30: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
8a40: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8a50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8a60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8a70: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8a80: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8a90: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8ab0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8ac0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
8ad0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
8ae0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8af0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8b00: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8b10: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8b20: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8b30: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8b40: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8b60: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8b70: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8b80: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8b90: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8ba0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8bb0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8bc0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8bd0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8be0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8bf0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8c00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8c10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8c20: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8c30: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8c40: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8c50: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8c60: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8c70: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8c80: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8c90: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8ca0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8cb0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8cc0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8cd0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8ce0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8cf0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8d00: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8d10: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8d20: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8d30: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8d40: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8d50: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8d60: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8d70: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8d80: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8d90: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8da0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8db0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8dc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8dd0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8de0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8df0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8e00: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8e10: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8e20: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8e30: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8e40: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8e50: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8e60: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8e70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8e80: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8e90: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8ea0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8eb0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8ee0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8ef0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f00: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8f10: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8f20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8f30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8f40: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8f50: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8f60: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8f70: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8f80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8f90: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8fa0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8fb0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8fc0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8fd0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8fe0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ff0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
9000: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
9010: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
9020: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
9030: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
9040: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
9050: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
9060: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9070: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9080: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
9090: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
90a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
90b0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
90c0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
90d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
90e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
90f0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
9100: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
9110: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9120: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9130: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
9140: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
9150: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
9160: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
9170: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
9180: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
9190: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
91a0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
91b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
91c0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
91d0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
91e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
91f0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
9200: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9210: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9220: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9230: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
9240: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
9250: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
9260: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
9270: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
9280: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
9290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
92a0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
92b0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
92c0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
92d0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
92e0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
92f0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
9300: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
9310: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9320: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9330: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
9340: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
9350: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9360: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
9370: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9380: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
9390: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
93a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
93b0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
93c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
93d0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
93e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
93f0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
9400: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9410: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9420: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9430: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
9440: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
9450: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
9460: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
9470: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
9480: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
9490: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
94a0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
94b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
94c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
94d0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
94e0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
94f0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9500: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9510: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9520: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9530: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9540: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9550: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9560: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9570: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
95a0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
95b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
95c0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
95d0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
95e0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
95f0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9600: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9610: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9620: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9630: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9640: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9650: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9660: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9670: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9680: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9690: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
96a0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
96b0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
96c0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
96d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
96e0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
96f0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9700: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9710: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9720: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9730: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9740: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49  TE_FCNTL_SIZE_LI
9750: 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  MIT]].** The [SQ
9760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9770: 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69 73  LIMIT] opcode is
9780: 20 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d 6f   used by in-memo
9790: 72 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 69  ry VFS that.** i
97a0: 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69 74  mplements [sqlit
97b0: 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29  e3_deserialize()
97c0: 5d 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70 65  ] to set an uppe
97d0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73  r bound on the s
97e0: 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  ize.** of the in
97f0: 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
9800: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9810: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9820: 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  a [sqlite3_int64
9830: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74  ]..** If the int
9840: 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  eger pointed to 
9850: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9860: 6e 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20 69  n it is filled i
9870: 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63 75  n with the.** cu
9880: 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f 74  rrent limit.  Ot
9890: 68 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d 69  herwise the limi
98a0: 74 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20  t is set to the 
98b0: 6c 61 72 67 65 72 20 6f 66 20 74 68 65 20 76 61  larger of the va
98c0: 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  lue.** of the in
98d0: 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f  teger pointed to
98e0: 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
98f0: 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e 20   database size. 
9900: 20 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   The integer.** 
9910: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73 65  pointed to is se
9920: 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69 6d  t to the new lim
9930: 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  it..**.** <li>[[
9940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
9950: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
9960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9970: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
9980: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
9990: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
99a0: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
99b0: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
99c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
99d0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
99e0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
99f0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
9a00: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
9a10: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
9a20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
9a30: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
9a40: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
9a50: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
9a60: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
9a70: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
9a80: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
9a90: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
9aa0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
9ab0: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
9ac0: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
9ad0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
9ae0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
9af0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
9b00: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9b10: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9b20: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
9b30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b40: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9b50: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9b60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9b70: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
9b80: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9b90: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9ba0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9bb0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9bc0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
9bd0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9be0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9bf0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9c00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9c10: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  NAL_POINTER]..**
9c20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9c30: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9c40: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9c50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
9c60: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f  URNAL_POINTER] o
9c70: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9c80: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9c90: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9ca0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9cb0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9cc0: 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69  h the journal fi
9cd0: 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68  le (either.** th
9ce0: 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  e [rollback jour
9cf0: 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69  nal] or the [wri
9d00: 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66  te-ahead log]) f
9d10: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
9d20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9d30: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9d40: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9d50: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  FILE_POINTER]..*
9d60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9d70: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9d80: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9d90: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9da0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9db0: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
9dc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9dd0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
9de0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9df0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
9e00: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9e10: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9e20: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
9e30: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
9e40: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
9e50: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
9e60: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
9e70: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
9e80: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9e90: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9ea0: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
9eb0: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
9ec0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
9ed0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
9ee0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
9ef0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
9f00: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9f10: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9f20: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
9f30: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
9f40: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
9f50: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
9f60: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
9f70: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
9f80: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9f90: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9fa0: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
9fb0: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
9fc0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
9fd0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
9fe0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
9ff0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
a000: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a010: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
a020: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
a030: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
a040: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
a050: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
a060: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
a070: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
a080: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
a090: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
a0a0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a0b0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
a0c0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
a0d0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
a0e0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
a0f0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
a100: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
a110: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
a120: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a130: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
a140: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
a150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
a160: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
a170: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
a180: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
a190: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
a1a0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
a1b0: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
a1c0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
a1d0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
a1e0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
a1f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
a200: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
a210: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
a220: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
a230: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
a240: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
a250: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
a260: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
a270: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a280: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
a290: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
a2a0: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
a2b0: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
a2c0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
a2d0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
a2e0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
a2f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
a300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
a310: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
a320: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a330: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
a340: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
a350: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
a360: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
a370: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
a380: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
a390: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
a3a0: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
a3b0: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
a3c0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
a3d0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
a3e0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
a3f0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
a400: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
a410: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
a420: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
a430: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
a440: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
a450: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
a460: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
a470: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
a480: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
a490: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
a4a0: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
a4b0: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
a4c0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
a4d0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
a4e0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
a4f0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
a500: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
a510: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
a520: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
a530: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
a540: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
a550: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
a560: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
a570: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
a580: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
a590: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
a5a0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
a5b0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
a5c0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
a5d0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
a5e0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
a5f0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
a600: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
a610: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e  integer is the n
a620: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
a630: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
a640: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
a650: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
a660: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
a670: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
a680: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
a690: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
a6a0: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
a6b0: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
a6c0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
a6d0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
a6e0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
a6f0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
a700: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
a710: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
a720: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
a730: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
a740: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
a750: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a760: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
a770: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a780: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a790: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a7a0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a7b0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a7c0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
a7d0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
a7e0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
a7f0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
a800: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
a810: 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61  g ([WAL file]) a
a820: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a830: 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66  .** files used f
a840: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
a850: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
a860: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
a870: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
a880: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
a890: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
a8a0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
a8b0: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
a8c0: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
a8d0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
a8e0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
a8f0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
a900: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
a910: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
a920: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
a930: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
a940: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
a950: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
a960: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
a970: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
a980: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
a990: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
a9a0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a9b0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a9c0: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a9d0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a9e0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a9f0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
aa00: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
aa10: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
aa20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
aa30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
aa40: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
aa50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
aa60: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
aa70: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
aa80: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
aa90: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
aaa0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
aab0: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
aac0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
aad0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
aae0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
aaf0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ab00: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
ab10: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
ab20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab30: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
ab40: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
ab50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
ab60: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
ab70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
ab80: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
ab90: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
aba0: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
abb0: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
abc0: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
abd0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
abe0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
abf0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
ac00: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
ac10: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
ac20: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
ac30: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
ac40: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
ac50: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
ac60: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ac70: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
ac80: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
ac90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
aca0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
acb0: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
acc0: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
acd0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
ace0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
acf0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
ad00: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
ad10: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
ad20: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
ad30: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ad40: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
ad50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
ad60: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ad70: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
ad80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ad90: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
ada0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
adb0: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
adc0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
add0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
ade0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
adf0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
ae00: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
ae10: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
ae20: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
ae30: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
ae40: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
ae50: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
ae60: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
ae70: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
ae80: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
ae90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
aea0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aeb0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
aec0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aed0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
aee0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
aef0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
af00: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
af10: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
af20: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
af30: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
af40: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
af50: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
af60: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
af70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
af80: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
af90: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
afa0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
afb0: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
afc0: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
afd0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
afe0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
aff0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b000: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
b010: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
b020: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
b030: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
b040: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
b050: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
b060: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
b070: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
b080: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
b090: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
b0a0: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
b0b0: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
b0c0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
b0d0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
b0e0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
b0f0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
b100: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
b110: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
b120: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
b130: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
b140: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
b150: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
b160: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b170: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
b180: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
b190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
b1a0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
b1b0: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
b1c0: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
b1d0: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
b1e0: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
b1f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
b200: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
b210: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
b220: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b230: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
b240: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
b250: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
b260: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
b270: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
b280: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
b290: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
b2a0: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
b2b0: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
b2c0: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
b2d0: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
b2e0: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
b2f0: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
b300: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
b310: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b320: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
b330: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
b340: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
b350: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
b360: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
b370: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b380: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
b390: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
b3a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
b3b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
b3c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
b3d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
b3e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
b3f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
b400: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
b410: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b420: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b430: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
b440: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
b450: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
b460: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
b470: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
b480: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
b490: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
b4a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
b4b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
b4c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
b4d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
b4e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
b4f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
b500: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
b510: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
b520: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b530: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
b540: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
b550: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
b560: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
b570: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
b580: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
b590: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b5a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
b5b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
b5c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
b5d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
b5e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
b5f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
b600: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
b610: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
b620: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
b630: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b640: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b650: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b660: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
b670: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
b680: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
b690: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
b6a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b6b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
b6c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
b6d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
b6e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
b6f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
b700: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
b710: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
b720: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
b730: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
b740: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
b750: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
b760: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
b770: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
b780: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
b790: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
b7a0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
b7b0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
b7c0: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
b7d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b7e0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
b7f0: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
b800: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
b810: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
b820: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
b830: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
b840: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
b850: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
b860: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
b870: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
b880: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
b890: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
b8a0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
b8b0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
b8c0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
b8d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b8e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
b8f0: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
b900: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
b910: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
b920: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
b930: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
b940: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
b950: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
b960: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b970: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b980: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
b990: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b9a0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b9b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b9c0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b9d0: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b9e0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b9f0: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ba00: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ba10: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ba20: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ba30: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ba40: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ba50: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ba60: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ba70: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ba80: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ba90: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
baa0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
bab0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
bac0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
bad0: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
bae0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
baf0: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
bb00: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
bb10: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
bb20: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
bb30: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
bb40: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
bb50: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
bb60: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
bb70: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
bb80: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
bb90: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
bba0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
bbb0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
bbc0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
bbd0: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
bbe0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
bbf0: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
bc00: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
bc10: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
bc20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bc30: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
bc40: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
bc50: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
bc60: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
bc70: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
bc80: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
bc90: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
bca0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
bcb0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
bcc0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
bcd0: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
bce0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
bcf0: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
bd00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
bd10: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
bd20: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
bd30: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
bd40: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
bd50: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
bd60: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
bd70: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
bd80: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
bd90: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
bda0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
bdb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
bdc0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
bdd0: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
bde0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
bdf0: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
be00: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
be10: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
be20: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
be30: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
be50: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
be60: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
be70: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
be80: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
be90: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
bea0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
beb0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
bec0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
bed0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
bee0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
bef0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
bf00: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
bf10: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
bf20: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
bf30: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
bf40: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
bf50: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
bf60: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
bf70: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
bf80: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
bf90: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
bfa0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
bfb0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
bfc0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
bfd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
bfe0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
bff0: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
c000: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
c010: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
c020: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
c030: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
c040: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
c050: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
c060: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
c070: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c080: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
c090: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c0a0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
c0b0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
c0c0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
c0d0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
c0e0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
c0f0: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
c100: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
c110: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
c120: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
c130: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
c140: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
c150: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
c160: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
c170: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
c180: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
c190: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
c1a0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
c1b0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
c1c0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
c1d0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
c1e0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
c1f0: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
c200: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
c210: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
c220: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
c230: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
c240: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
c250: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
c260: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
c270: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c280: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c290: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
c2a0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
c2b0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
c2c0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
c2d0: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
c2e0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
c2f0: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
c300: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
c310: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
c320: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
c330: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
c340: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c350: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c360: 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  GET_HANDLE]].** 
c370: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c380: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
c390: 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  LE] opcode can b
c3a0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
c3b0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
c3c0: 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68  ng native file h
c3d0: 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64  andle associated
c3e0: 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e   with a file han
c3f0: 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a  dle.  This file.
c400: 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  ** control inter
c410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
c420: 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20  nt as a pointer 
c430: 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65  to a native file
c440: 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77   handle and.** w
c450: 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74  rites the result
c460: 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e  ing value there.
c470: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c480: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c490: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
c4a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c4b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
c4c0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
c4d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
c4e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
c4f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
c500: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c510: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
c520: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
c530: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
c540: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
c550: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
c560: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
c570: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c580: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
c590: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
c5a0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
c5b0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
c5c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c5d0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c5e0: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c600: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
c610: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
c620: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
c630: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
c640: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
c650: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
c660: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
c670: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
c680: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
c690: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
c6a0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
c6b0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
c6c0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
c6d0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
c6e0: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
c6f0: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
c700: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
c710: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
c720: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
c730: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
c740: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c750: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
c760: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c770: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
c780: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
c790: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
c7a0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
c7b0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
c7c0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c7d0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
c7e0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
c7f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c800: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
c810: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
c820: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c830: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
c840: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
c850: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
c860: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
c870: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
c880: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c890: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
c8a0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a  is opcode.  .**.
c8b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c8c0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c8d0: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66  IC_WRITE]].** If
c8e0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
c8f0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
c900: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65  WRITE] opcode re
c910: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c  turns SQLITE_OK,
c920: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c   then.** the fil
c930: 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20  e descriptor is 
c940: 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68  placed in "batch
c950: 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68   write mode", wh
c960: 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c  ich.** means all
c970: 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74   subsequent writ
c980: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c  e operations wil
c990: 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e  l be deferred an
c9a0: 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63  d done.** atomic
c9b0: 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74  ally at the next
c9c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
c9d0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
c9e0: 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a  TE].  Systems.**
c9f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70   that do not sup
ca00: 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69  port batch atomi
ca10: 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65  c writes will re
ca20: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
ca30: 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77  OUND..** ^Follow
ca40: 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c  ing a successful
ca50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45   SQLITE_FCNTL_BE
ca60: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
ca70: 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a   and prior to.**
ca80: 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51   the closing [SQ
ca90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
caa0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  T_ATOMIC_WRITE] 
cab0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  or.** [SQLITE_FC
cac0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cad0: 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69  MIC_WRITE], SQLi
cae0: 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20  te will make.** 
caf0: 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  no VFS interface
cb00: 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61   calls on the sa
cb10: 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  me [sqlite3_file
cb20: 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  ] file descripto
cb30: 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20  r.** except for 
cb40: 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72  calls to the xWr
cb50: 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74  ite method and t
cb60: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
cb70: 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b  method.** with [
cb80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
cb90: 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  E_HINT]..**.** <
cba0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
cbb0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
cbc0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  WRITE]].** The [
cbd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
cbe0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
cbf0: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  ] opcode causes 
cc00: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65  all write.** ope
cc10: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68  rations since th
cc20: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65  e previous succe
cc30: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
cc40: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
cc50: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cc60: 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72  TE] to be perfor
cc70: 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a  med atomically..
cc80: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
cc90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
cca0: 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20  LITE_OK] if and 
ccb0: 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74  only if the writ
ccc0: 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70  es were.** all p
ccd0: 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73  erformed success
cce0: 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62  fully and have b
ccf0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f  een committed to
cd00: 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72   persistent stor
cd10: 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  age..** ^Regardl
cd20: 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
cd30: 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63  r not it is succ
cd40: 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c  essful, this fil
cd50: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a  e control takes.
cd60: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  ** the file desc
cd70: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61  riptor out of ba
cd80: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73  tch write mode s
cd90: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cda0: 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f  quent.** write o
cdb0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e  perations are in
cdc0: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53  dependent..** ^S
cdd0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
cde0: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46   invoke SQLITE_F
cdf0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
ce00: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74  IC_WRITE without
ce10: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63  .** a prior succ
ce20: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
ce30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
ce40: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
ce50: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
ce70: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
ce80: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
ce90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
cea0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f  _ATOMIC_WRITE] o
ceb0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c  pcode causes all
cec0: 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74   write.** operat
ced0: 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70  ions since the p
cee0: 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66  revious successf
cef0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b  ul call to .** [
cf00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
cf10: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
cf20: 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61   to be rolled ba
cf30: 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c  ck..** ^This fil
cf40: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20  e control takes 
cf50: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
cf60: 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68  tor out of batch
cf70: 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73   write mode.** s
cf80: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cf90: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72  quent write oper
cfa0: 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70  ations are indep
cfb0: 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69  endent..** ^SQLi
cfc0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
cfd0: 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  voke SQLITE_FCNT
cfe0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
cff0: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a  C_WRITE without.
d000: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  ** a prior succe
d010: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53  ssful call to [S
d020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
d030: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  N_ATOMIC_WRITE].
d040: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d050: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54  ITE_FCNTL_LOCK_T
d060: 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20  IMEOUT]].** The 
d070: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
d080: 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f  CK_TIMEOUT] opco
d090: 64 65 20 63 61 75 73 65 73 20 61 74 74 65 6d 70  de causes attemp
d0a0: 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ts to obtain.** 
d0b0: 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e  a file lock usin
d0c0: 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78  g the xLock or x
d0d0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20  ShmLock methods 
d0e0: 6f 66 20 74 68 65 20 56 46 53 20 74 6f 20 77 61  of the VFS to wa
d0f0: 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20  it.** for up to 
d100: 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  M milliseconds b
d110: 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77  efore failing, w
d120: 68 65 72 65 20 4d 20 69 73 20 74 68 65 20 73 69  here M is the si
d130: 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65  ngle .** unsigne
d140: 64 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65  d integer parame
d150: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
d160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
d170: 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20  TA_VERSION]].** 
d180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d190: 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20  L_DATA_VERSION] 
d1a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
d1b0: 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73  o detect changes
d1c0: 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73   to.** a databas
d1d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67  e file.  The arg
d1e0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
d1f0: 65 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75  er to a 32-bit u
d200: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e  nsigned integer.
d210: 0a 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76 65  .** The "data ve
d220: 72 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70  rsion" for the p
d230: 61 67 65 72 20 69 73 20 77 72 69 74 74 65 6e 20  ager is written 
d240: 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72  into the pointer
d250: 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20  .  The.** "data 
d260: 76 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73  version" changes
d270: 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68   whenever any ch
d280: 61 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74  ange occurs to t
d290: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
d2a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
d2b0: 65 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75 67  e, either throug
d2c0: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  h SQL statements
d2d0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
d2e0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
d2f0: 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74  ion or through t
d300: 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d  ransactions comm
d310: 69 74 74 65 64 20 62 79 20 73 65 70 61 72 61 74  itted by separat
d320: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
d330: 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62  nnections possib
d340: 6c 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63  ly in other proc
d350: 65 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69  esses. The [sqli
d360: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
d370: 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  s()].** interfac
d380: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
d390: 20 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74   find if any dat
d3a0: 61 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e  abase on the con
d3b0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e  nection has chan
d3c0: 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74  ged,.** but that
d3d0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f   interface respo
d3e0: 6e 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f  nds to changes o
d3f0: 6e 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61  n TEMP as well a
d400: 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a  s MAIN and does.
d410: 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  ** not provide a
d420: 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65   mechanism to de
d430: 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20  tect changes to 
d440: 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f  MAIN only.  Also
d450: 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
d460: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d470: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
d480: 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61  ponds to interna
d490: 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61  l changes only a
d4a0: 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e  nd.** omits chan
d4b0: 67 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65  ges made by othe
d4c0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
d4d0: 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
d4e0: 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72  [PRAGMA data_ver
d4f0: 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72  sion] command pr
d500: 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73  ovide a mechanis
d510: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d520: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67  ges to.** a sing
d530: 6c 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  le attached data
d540: 62 61 73 65 20 74 68 61 74 20 6f 63 63 75 72 20  base that occur 
d550: 64 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74  due to other dat
d560: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d570: 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20  s,.** but omits 
d580: 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e  changes implemen
d590: 74 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  ted by the datab
d5a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
d5b0: 6e 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a  n which it is.**
d5c0: 20 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66   called.  This f
d5d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74  ile control is t
d5e0: 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73  he only mechanis
d5f0: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d600: 67 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70  ges that.** happ
d610: 65 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e  en either intern
d620: 61 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c  ally or external
d630: 6c 79 20 61 6e 64 20 74 68 61 74 20 61 72 65 20  ly and that are 
d640: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
d650: 2a 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ** a particular 
d660: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
d670: 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  e..** </ul>.*/.#
d680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d690: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
d6a0: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
d6b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d6c0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d6d0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
d6e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d6f0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
d700: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
d710: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d720: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
d730: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
d740: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d750: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
d760: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
d770: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d780: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
d790: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
d7a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
d7b0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
d7c0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
d7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
d7e0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
d7f0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
d800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d810: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
d820: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
d830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
d840: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
d850: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
d860: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
d870: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
d880: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
d890: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d8b0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
d8c0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
d8d0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
d8e0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
d8f0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
d900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
d910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d920: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
d930: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
d940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d950: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
d960: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
d970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d980: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
d990: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
d9a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d9b0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
d9c0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
d9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d9e0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
d9f0: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
da00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
da10: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
da20: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
da30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
da40: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
da50: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
da60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
da70: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
da80: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
da90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
daa0: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
dab0: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20       24.#define 
dac0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
dad0: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20  VFS             
dae0: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53      25.#define S
daf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20  QLITE_FCNTL_RBU 
db00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
db10: 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51     26.#define SQ
db20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
db30: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
db40: 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c    27.#define SQL
db50: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
db60: 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  L_POINTER       
db70: 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   28.#define SQLI
db80: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
db90: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
dba0: 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  29.#define SQLIT
dbb0: 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20  E_FCNTL_PDB     
dbc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
dbd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
dbe0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
dbf0: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31  MIC_WRITE     31
dc00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc10: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
dc20: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a  MIC_WRITE    32.
dc30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dc40: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
dc50: 4f 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23  OMIC_WRITE  33.#
dc60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dc70: 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54  NTL_LOCK_TIMEOUT
dc80: 20 20 20 20 20 20 20 20 20 20 20 33 34 0a 23 64             34.#d
dc90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dca0: 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20  TL_DATA_VERSION 
dcb0: 20 20 20 20 20 20 20 20 20 20 33 35 0a 23 64 65            35.#de
dcc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dcd0: 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20 20  L_SIZE_LIMIT    
dce0: 20 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a 20           36../* 
dcf0: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
dd00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dd10: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
dd20: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
dd30: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
dd40: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
dd50: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
dd60: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
dd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
dd80: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
dd90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
dda0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
ddb0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
ddc0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
ddd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
dde0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
ddf0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
de00: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
de10: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
de20: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
de30: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
de40: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
de50: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
de60: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
de70: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
de80: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
de90: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
dea0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
deb0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
dec0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
ded0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
dee0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
def0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
df00: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
df10: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
df20: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
df30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
df40: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
df50: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
df60: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  EF: Loadable Ext
df70: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a  ension Thunk.**.
df80: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
df90: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74  the opaque sqlit
dfa0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
dfb0: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73  structure is pas
dfc0: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68  sed as.** the th
dfd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
dfe0: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66   entry points of
dff0: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e   [loadable exten
e000: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a  sions].  This.**
e010: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
e020: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20  be typedefed in 
e030: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72  order to work ar
e040: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61  ound compiler wa
e050: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d  rnings.** on som
e060: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a  e platforms..*/.
e070: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
e080: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
e090: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  nes sqlite3_api_
e0a0: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a  routines;../*.**
e0b0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
e0c0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
e0d0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
e0e0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
e0f0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
e100: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
e110: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
e120: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
e130: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
e140: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
e150: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
e160: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
e170: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
e180: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
e190: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
e1a0: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
e1b0: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
e1c0: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
e1d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
e1e0: 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  The VFS interfac
e1f0: 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65  e is sometimes e
e200: 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e  xtended by addin
e210: 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e  g new methods on
e220: 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20  to.** the end.  
e230: 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61  Each time such a
e240: 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75  n extension occu
e250: 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e  rs, the iVersion
e260: 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63   field.** is inc
e270: 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69  remented.  The i
e280: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74  Version value st
e290: 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69  arted out as 1 i
e2a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72  n.** SQLite [ver
e2b0: 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b  sion 3.5.0] on [
e2c0: 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74  dateof:3.5.0], t
e2d0: 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f  hen increased to
e2e0: 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74   2.** with SQLit
e2f0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30  e [version 3.7.0
e300: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37  ] on [dateof:3.7
e310: 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e  .0], and then in
e320: 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20  creased.** to 3 
e330: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72  with SQLite [ver
e340: 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b  sion 3.7.6] on [
e350: 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20  dateof:3.7.6].  
e360: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
e370: 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65  s.** may be appe
e380: 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69  nded to the sqli
e390: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61  te3_vfs object a
e3a0: 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  nd the iVersion 
e3b0: 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63  value.** may inc
e3c0: 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66  rease again in f
e3d0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
e3e0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74  f SQLite..** Not
e3f0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
e400: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
e410: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e420: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
e430: 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d   transition from
e440: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
e450: 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76  ion 3.5.9] to [v
e460: 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e  ersion 3.6.0] on
e470: 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a   [dateof:3.6.0].
e480: 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  ** and yet the i
e490: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
e4a0: 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a  s not modified..
e4b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
e4c0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
e4d0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
e4e0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
e4f0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
e500: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
e510: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
e520: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
e530: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
e540: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
e550: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
e560: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
e570: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
e580: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
e590: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
e5a0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
e5b0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
e5c0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
e5d0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
e5e0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
e5f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
e600: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
e610: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
e620: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
e630: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
e640: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
e650: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
e660: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
e670: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
e680: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
e690: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
e6a0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
e6b0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
e6c0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
e6d0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
e6e0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
e6f0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
e700: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
e710: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
e720: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
e730: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
e740: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
e750: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
e760: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
e770: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
e780: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e790: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
e7a0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
e7b0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
e7c0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
e7d0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
e7e0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
e7f0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
e800: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
e810: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
e820: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
e830: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
e840: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
e850: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
e860: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
e870: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
e880: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
e890: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
e8a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
e8b0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
e8c0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
e8d0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
e8e0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
e8f0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
e900: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
e910: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
e920: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
e930: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
e940: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e950: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
e960: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
e970: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
e980: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
e990: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
e9a0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
e9b0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
e9c0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
e9d0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
e9e0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
e9f0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
ea00: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
ea10: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
ea20: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
ea30: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
ea40: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
ea50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ea60: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ea70: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ea80: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
ea90: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
eaa0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
eab0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
eac0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
ead0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
eae0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
eaf0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
eb00: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
eb10: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
eb20: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
eb30: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
eb40: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
eb50: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
eb60: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
eb70: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
eb80: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
eb90: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
eba0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
ebb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
ebc0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
ebd0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
ebe0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
ebf0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
ec00: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
ec10: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
ec20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
ec30: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
ec40: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ec50: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
ec60: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
ec70: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
ec80: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
ec90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
eca0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
ecb0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ecc0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
ecd0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
ece0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
ecf0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
ed00: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
ed10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ed20: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
ed30: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
ed40: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
ed50: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
ed60: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ed70: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ed80: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ed90: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
eda0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
edb0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
edc0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
edd0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ede0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
edf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ee00: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
ee10: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
ee30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ee40: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
ee50: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ee60: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ee70: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
ee80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
ee90: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
eea0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
eeb0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
eec0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
eed0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
eee0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
eef0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
ef00: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
ef10: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ef20: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
ef30: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
ef40: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
ef50: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
ef60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ef70: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
ef80: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
ef90: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
efa0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
efb0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
efc0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
efd0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
efe0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
eff0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
f000: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
f010: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
f020: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
f030: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
f040: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
f050: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f060: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
f070: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
f080: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
f090: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
f0a0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
f0b0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
f0c0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
f0d0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
f0e0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
f0f0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
f100: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
f110: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
f120: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
f130: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
f140: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
f160: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f170: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
f180: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
f190: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
f1a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
f1b0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f1c0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
f1d0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
f1e0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
f1f0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
f200: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
f210: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
f220: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
f230: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
f240: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
f250: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
f260: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
f270: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
f280: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
f290: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f2a0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
f2b0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
f2c0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
f2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f2e0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
f2f0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
f300: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
f310: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
f320: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
f330: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
f340: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
f350: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
f360: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
f370: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
f380: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
f390: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
f3a0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
f3b0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
f3c0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
f3d0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
f3e0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
f3f0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
f400: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
f410: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
f420: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
f430: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
f440: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
f450: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
f460: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
f470: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
f480: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
f490: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
f4a0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
f4b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
f4c0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
f4d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
f4e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
f4f0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
f500: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
f510: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
f520: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
f530: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
f540: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
f550: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
f560: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
f570: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
f580: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
f590: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
f5a0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
f5b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
f5c0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
f5d0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
f5e0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
f5f0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
f600: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
f610: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
f620: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
f630: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
f640: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
f650: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
f660: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
f670: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
f680: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
f690: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
f6a0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
f6b0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
f6c0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
f6d0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
f6e0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
f6f0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
f700: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
f710: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
f720: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f730: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
f740: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
f750: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
f760: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
f770: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f780: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
f790: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
f7a0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
f7b0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
f7c0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
f7d0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
f7e0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
f7f0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
f800: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
f810: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
f820: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
f830: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
f840: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
f850: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
f860: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
f870: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
f880: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
f890: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
f8a0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
f8b0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
f8c0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
f8d0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
f8e0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
f8f0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
f900: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
f910: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
f920: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
f930: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
f940: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
f950: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
f960: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
f970: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
f980: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
f990: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
f9a0: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
f9b0: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
f9c0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
f9d0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
f9e0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
f9f0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
fa00: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
fa10: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
fa20: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
fa30: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
fa40: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
fa50: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
fa60: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
fa70: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
fa80: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
fa90: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
faa0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
fab0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
fac0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
fad0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
fae0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
faf0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
fb00: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
fb10: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
fb20: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
fb30: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
fb40: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
fb50: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
fb60: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
fb70: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
fb80: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
fb90: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
fba0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
fbb0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
fbc0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
fbd0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
fbe0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
fbf0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
fc00: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
fc10: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
fc20: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
fc30: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
fc40: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
fc50: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
fc60: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
fc70: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
fc80: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
fc90: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
fca0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
fcb0: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
fcc0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
fcd0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
fce0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
fcf0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
fd00: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
fd10: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
fd20: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
fd30: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
fd40: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
fd50: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
fd60: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
fd70: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
fd80: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
fd90: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
fda0: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
fdb0: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
fdc0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
fdd0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
fde0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
fdf0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
fe00: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
fe10: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
fe20: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
fe30: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
fe40: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
fe50: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
fe60: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
fe70: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
fe80: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
fe90: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
fea0: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
feb0: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
fec0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
fed0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
fee0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
fef0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
ff00: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
ff10: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
ff20: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
ff30: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
ff40: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
ff50: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
ff60: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
ff70: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
ff80: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
ff90: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
ffa0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
ffb0: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
ffc0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
ffd0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
ffe0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
fff0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
10000 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
10010 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
10020 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
10030 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
10040 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
10050 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
10060 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
10070 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
10080 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
10090 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
100a0 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
100b0 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
100c0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
100d0 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
100e0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
100f0 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
10100 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
10110 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
10120 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
10130 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
10140 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
10150 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
10160 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
10170 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
10180 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
10190 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
101a0 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
101b0 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
101c0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
101d0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
101e0 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
101f0 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
10200 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
10210 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
10220 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10230 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
10240 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
10250 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
10260 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
10270 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
10280 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
10290 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
102a0 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
102b0 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
102c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
102d0 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
102e0 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
102f0 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
10300 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
10310 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
10320 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10330 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10340 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
10350 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
10360 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10370 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10380 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
10390 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
103a0 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
103b0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
103c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
103d0 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
103e0 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
103f0 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
10400 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10410 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
10420 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
10430 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
10440 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
10450 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
10460 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
10470 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
10480 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
10490 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
104a0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
104b0 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
104c0 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
104d0 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
104e0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
104f0 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
10500 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
10510 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
10520 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
10530 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
10540 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
10550 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
10560 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
10570 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
10580 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
10590 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
105a0 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
105b0 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
105c0 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
105d0 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
105e0 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
105f0 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
10600 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
10610 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
10620 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
10630 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10640 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
10650 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
10660 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
10670 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
10680 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
10690 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
106a0 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
106b0 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
106c0 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
106d0 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
106e0 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
106f0 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
10700 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10710 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
10720 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
10730 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
10740 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
10750 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
10760 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10770 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
10780 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
10790 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
107a0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
107b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
107c0 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
107d0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
107e0 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
107f0 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
10800 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
10810 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
10820 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
10830 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
10840 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
10850 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
10860 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
10870 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
10880 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
10890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
108a0 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
108b0 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
108c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
108d0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
108e0 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
108f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
10900 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
10910 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
10920 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
10930 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
10940 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
10950 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
10960 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
10970 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
10980 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
10990 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
109a0 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
109b0 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
109c0 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
109d0 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
109e0 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
109f0 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10a00 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10a10 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
10a20 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
10a30 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
10a40 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
10a50 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
10a60 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
10a70 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
10a80 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
10a90 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
10aa0 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
10ab0 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
10ac0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10ad0 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
10ae0 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
10af0 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
10b00 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
10b10 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
10b20 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
10b30 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
10b40 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
10b50 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
10b60 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10b70 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10b80 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
10b90 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
10ba0 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
10bb0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10bc0 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
10bd0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
10be0 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
10bf0 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
10c00 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
10c10 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
10c20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10c30 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
10c40 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
10c50 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10c60 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
10c70 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
10c80 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
10c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10ca0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
10cb0 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
10cc0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
10cd0 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
10ce0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
10cf0 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
10d00 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
10d10 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
10d20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
10d30 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
10d40 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
10d50 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
10d60 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
10d70 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
10d80 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
10d90 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
10da0 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
10db0 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
10dc0 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
10dd0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
10de0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10df0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
10e00 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
10e10 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10e20 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10e30 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
10e40 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
10e50 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10e60 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10e70 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
10e80 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
10e90 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
10ea0 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
10eb0 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
10ec0 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
10ed0 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
10ee0 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
10ef0 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
10f00 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
10f10 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
10f20 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
10f30 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
10f40 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
10f50 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
10f60 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
10f70 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
10f80 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
10f90 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
10fa0 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
10fb0 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
10fc0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10fd0 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
10fe0 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
10ff0 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
11000 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
11010 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
11020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
11030 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
11040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11050 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
11060 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
11070 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
11080 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
11090 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
110a0 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
110b0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
110c0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
110d0 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
110e0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
110f0 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
11100 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
11110 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
11120 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
11130 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
11140 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
11150 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
11160 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
11170 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
11180 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
11190 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
111a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
111b0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
111c0 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
111d0 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
111e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
111f0 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
11200 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
11210 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
11220 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
11230 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
11240 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
11250 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11260 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
11270 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
11280 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
11290 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
112a0 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
112b0 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
112c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
112d0 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
112e0 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
112f0 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
11300 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
11310 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
11320 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
11330 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
11340 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
11350 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
11360 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
11370 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11380 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
11390 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
113a0 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
113b0 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
113c0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
113d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
113e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
113f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
11400 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
11410 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
11420 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
11430 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
11440 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
11450 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
11460 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
11470 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
11480 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
11490 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
114a0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
114b0 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
114c0 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
114d0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
114e0 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
114f0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
11500 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
11510 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11520 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
11530 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
11540 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
11550 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
11560 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
11570 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
11580 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
11590 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
115a0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
115b0 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
115c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
115d0 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
115e0 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
115f0 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
11600 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
11610 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
11620 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
11630 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
11640 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
11650 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
11660 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
11670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11680 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
11690 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
116a0 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
116b0 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
116c0 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
116d0 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
116e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
116f0 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
11700 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
11710 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
11720 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
11730 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
11740 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
11750 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
11760 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
11770 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
11780 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
11790 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
117a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
117b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
117c0 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
117d0 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
117e0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
117f0 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
11800 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
11810 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
11820 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
11830 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
11840 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
11850 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
11860 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
11870 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
11880 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
11890 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
118a0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
118b0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
118c0 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
118d0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
118e0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
118f0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
11900 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
11910 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
11920 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
11930 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11940 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
11950 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
11960 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
11970 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
11980 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
11990 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
119a0 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
119b0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
119c0 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
119d0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
119e0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
119f0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
11a00 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
11a10 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
11a20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11a30 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
11a40 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
11a50 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
11a60 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
11a70 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
11a80 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
11a90 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
11aa0 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
11ab0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
11ac0 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
11ad0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
11ae0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
11af0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
11b00 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11b10 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
11b20 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
11b30 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
11b40 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
11b50 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
11b60 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
11b70 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
11b80 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
11b90 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
11ba0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
11bb0 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
11bc0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
11bd0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
11be0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11bf0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
11c00 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
11c10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11c20 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
11c30 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
11c40 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
11c50 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
11c60 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
11c70 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
11c80 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
11c90 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11ca0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
11cb0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
11cc0 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
11cd0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
11ce0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11cf0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
11d00 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
11d10 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
11d20 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
11d30 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
11d40 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
11d50 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
11d60 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
11d70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
11d80 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
11d90 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
11da0 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
11db0 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
11dc0 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
11dd0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
11de0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
11df0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
11e00 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
11e10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
11e20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
11e30 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
11e40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
11e50 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
11e60 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
11e70 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
11e80 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
11e90 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
11ea0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11eb0 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
11ec0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
11ed0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
11ee0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11ef0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11f00 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
11f10 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
11f20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
11f30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11f40 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
11f50 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
11f60 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
11f70 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
11f80 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
11f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
11fa0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
11fb0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11fc0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
11fd0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11fe0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
11ff0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
12000 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
12010 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
12020 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
12030 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
12040 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
12050 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
12060 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
12070 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
12080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
12090 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
120a0 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
120b0 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
120c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
120d0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
120e0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
120f0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
12100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
12110 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
12120 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
12130 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
12140 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12150 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
12160 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
12170 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
12180 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
12190 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
121a0 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
121b0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
121c0 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
121d0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
121e0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
121f0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
12200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12210 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
12220 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
12230 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12240 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
12250 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
12260 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
12270 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
12280 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
12290 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
122a0 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
122b0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
122c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
122d0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
122e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
122f0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
12300 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
12310 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
12320 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
12330 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
12340 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
12350 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
12360 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
12370 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
12380 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
12390 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
123a0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
123b0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
123c0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
123d0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
123e0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
123f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
12400 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
12410 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
12420 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
12430 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
12440 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
12450 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
12460 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
12470 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
12480 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
12490 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
124a0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
124b0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
124c0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
124d0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
124e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
124f0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
12500 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
12510 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
12520 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
12530 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
12540 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
12550 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
12560 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
12570 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
12580 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
12590 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
125a0 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
125b0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
125c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
125d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
125e0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
125f0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
12600 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12610 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
12620 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
12630 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
12640 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
12650 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
12660 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
12670 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
12680 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
12690 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
126a0 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
126b0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
126c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
126d0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
126e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
126f0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
12700 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12710 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
12720 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
12730 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
12740 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
12750 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
12760 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
12770 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
12780 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
12790 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
127a0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
127b0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
127c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
127d0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
127e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
127f0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
12800 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
12810 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
12820 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12830 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
12840 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
12850 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
12860 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
12870 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
12880 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
12890 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
128a0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
128b0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
128c0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
128d0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
128e0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
128f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12900 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
12910 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12920 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
12930 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12940 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
12950 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
12960 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
12970 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12980 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
12990 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
129a0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
129b0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
129c0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
129d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
129e0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
129f0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
12a00 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
12a10 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
12a20 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
12a30 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
12a40 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
12a50 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12a60 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
12a70 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
12a80 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
12a90 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
12aa0 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
12ab0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12ac0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
12ad0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
12ae0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
12af0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
12b00 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
12b10 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12b20 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
12b30 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
12b40 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
12b50 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
12b60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12b70 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
12b80 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
12b90 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
12ba0 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
12bb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
12bc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12bd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
12be0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
12bf0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
12c00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12c10 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
12c20 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12c30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
12c40 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
12c50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12c60 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
12c70 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
12c80 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12c90 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
12ca0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
12cb0 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
12cc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12cd0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
12ce0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
12cf0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
12d00 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12d10 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12d20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
12d30 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
12d40 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
12d50 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
12d60 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
12d70 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
12d80 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
12d90 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
12da0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
12db0 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
12dc0 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
12dd0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
12de0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
12df0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12e00 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
12e10 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
12e20 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
12e30 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
12e40 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
12e50 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
12e60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12e70 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
12e80 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
12e90 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
12ea0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
12eb0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
12ec0 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
12ed0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
12ee0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
12ef0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
12f00 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
12f10 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
12f20 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
12f30 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
12f40 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
12f50 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
12f60 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
12f70 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
12f80 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
12f90 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
12fa0 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
12fb0 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
12fc0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
12fd0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
12fe0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12ff0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
13000 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
13010 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
13020 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
13030 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
13040 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
13050 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
13060 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
13070 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
13080 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
13090 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
130a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
130b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
130c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
130d0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
130e0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
130f0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
13100 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
13110 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
13120 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
13130 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
13140 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
13150 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
13160 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
13170 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
13180 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
13190 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
131a0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
131b0 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
131c0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
131d0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
131e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
131f0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
13200 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
13210 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
13220 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
13230 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
13240 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
13250 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
13260 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
13270 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
13280 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
13290 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
132a0 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
132b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
132c0 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
132d0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
132e0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
132f0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
13300 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
13310 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13320 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
13330 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
13340 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
13350 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13360 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
13370 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
13380 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
13390 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
133a0 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
133b0 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
133c0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
133d0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
133e0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
133f0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
13400 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
13410 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
13420 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
13430 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
13440 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
13450 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
13460 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
13470 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
13480 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
13490 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
134a0 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
134b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
134c0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
134d0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
134e0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
134f0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
13500 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
13510 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
13520 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
13530 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
13540 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
13550 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
13560 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
13570 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
13580 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
13590 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
135a0 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
135b0 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
135c0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
135d0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
135e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
135f0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
13600 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
13610 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13620 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
13630 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
13640 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
13650 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
13660 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
13670 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
13680 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
13690 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
136a0 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
136b0 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
136c0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
136d0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
136e0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
136f0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
13700 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
13710 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
13720 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
13730 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
13740 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
13750 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
13760 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
13770 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
13780 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
13790 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
137a0 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
137b0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
137c0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
137d0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
137e0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
137f0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
13800 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
13810 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
13820 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
13830 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
13840 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
13850 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
13860 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
13870 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
13880 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
13890 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
138a0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
138b0 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
138c0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
138d0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
138e0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
138f0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
13900 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
13910 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
13920 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
13930 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
13940 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
13950 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
13960 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
13970 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
13980 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
13990 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
139a0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
139b0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
139c0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
139d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
139e0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
139f0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
13a00 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
13a10 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
13a20 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
13a30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
13a40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13a50 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
13a60 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
13a70 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
13a80 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
13a90 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
13aa0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
13ab0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
13ac0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
13ad0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
13ae0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
13af0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
13b00 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
13b10 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
13b20 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
13b30 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
13b40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13b50 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
13b60 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
13b70 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
13b80 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
13b90 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
13ba0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13bb0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
13bc0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
13bd0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
13be0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13bf0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
13c00 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
13c10 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
13c20 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
13c30 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
13c40 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
13c50 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
13c60 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
13c70 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
13c80 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13c90 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
13ca0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
13cb0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13cc0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13cd0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13ce0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13cf0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13d00 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13d10 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
13d20 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
13d30 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
13d40 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
13d50 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
13d60 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
13d70 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
13d80 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
13d90 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
13da0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13db0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13dc0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13dd0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13de0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13df0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13e00 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
13e10 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
13e20 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
13e30 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
13e40 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
13e50 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
13e60 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
13e70 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13e80 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
13e90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
13ea0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13eb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13ec0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
13ed0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13ee0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13ef0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13f00 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
13f10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13f20 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
13f30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13f40 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
13f50 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
13f60 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
13f70 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
13f80 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
13f90 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
13fa0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
13fb0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
13fc0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
13fd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13fe0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13ff0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
14000 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
14010 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
14020 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
14030 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
14040 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14050 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
14060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
14070 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
14080 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
14090 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
140a0 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
140b0 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
140c0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
140d0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
140e0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
140f0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
14100 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
14110 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14120 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
14130 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
14140 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14150 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14160 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14170 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14180 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14190 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
141a0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
141b0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
141c0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
141d0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
141e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
141f0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
14200 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14210 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
14220 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
14230 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
14240 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14250 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
14260 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14270 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
14280 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14290 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
142a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
142b0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
142c0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
142d0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
142e0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
142f0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
14300 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
14310 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
14320 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
14330 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
14340 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
14350 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
14360 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
14370 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
14380 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
14390 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
143a0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
143b0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
143c0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
143d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
143e0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
143f0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
14400 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
14410 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
14420 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
14430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14440 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
14450 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
14460 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
14470 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
14480 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
14490 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
144a0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
144b0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
144c0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
144d0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
144e0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
144f0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
14500 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14510 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14520 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14530 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
14540 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14550 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
14560 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
14570 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
14580 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
14590 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
145a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
145b0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
145c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
145d0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
145e0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
145f0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
14600 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14610 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14620 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14630 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
14640 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
14650 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14660 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14670 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
14680 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14690 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
146a0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
146b0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
146c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
146d0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
146e0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
146f0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
14700 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
14710 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
14720 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
14730 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
14740 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
14750 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14760 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
14770 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
14780 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
14790 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
147a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
147b0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
147c0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
147d0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
147e0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
147f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
14800 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
14810 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14820 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
14830 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14840 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
14850 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14860 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14870 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
14880 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14890 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
148a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
148b0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
148c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
148d0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
148e0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
148f0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
14900 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14910 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14920 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14930 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
14940 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
14950 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
14960 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
14970 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
14980 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
14990 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
149a0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
149b0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
149c0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
149d0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
149e0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
149f0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
14a00 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
14a10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14a20 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20  _SMALL_MALLOC]] 
14a30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14a40 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f  G_SMALL_MALLOC</
14a50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
14a60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14a70 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  MALL_MALLOC opti
14a80 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
14a90 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74  argument of.** t
14aa0 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
14ab0 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
14ac0 6e 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65  n, which if true
14ad0 20 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74   provides a hint
14ae0 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68   to.** SQLite th
14af0 61 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f  at it should avo
14b00 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20  id large memory 
14b10 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70  allocations if p
14b20 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69  ossible..** SQLi
14b30 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74  te will run fast
14b40 65 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65  er if it is free
14b50 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d   to make large m
14b60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14b70 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61  s,.** but some a
14b80 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
14b90 20 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73   prefer to run s
14ba0 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67  lower in exchang
14bb0 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74  e for.** guarant
14bc0 65 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79  ees about memory
14bd0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74   fragmentation t
14be0 68 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65  hat are possible
14bf0 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c   if large.** all
14c00 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f  ocations are avo
14c10 69 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74  ided.  This hint
14c20 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66   is normally off
14c30 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14c40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14c50 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
14c60 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
14c70 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
14c80 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14c90 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14ca0 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
14cb0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14cc0 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
14cd0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
14ce0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
14cf0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
14d00 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
14d10 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
14d20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14d30 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
14d40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14d50 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
14d60 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
14d70 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
14d80 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
14d90 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
14da0 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
14db0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14dc0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
14dd0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
14de0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
14df0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
14e00 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
14e10 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
14e20 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14e30 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
14e40 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
14e50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14e60 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
14e70 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
14e80 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
14e90 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
14ea0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
14eb0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
14ec0 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
14ed0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14ee0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14ef0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
14f00 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
14f10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14f20 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
14f30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14f40 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
14f50 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
14f60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14f70 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20  CH option is no 
14f80 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20  longer used..** 
14f90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14fb0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
14fc0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14fd0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
14fe0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14ff0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
15000 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
15010 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
15020 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
15030 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
15040 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
15050 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
15060 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
15070 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
15080 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
15090 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
150a0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
150b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
150c0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
150d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
150e0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
150f0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
15100 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
15110 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
15120 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
15130 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15140 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
15150 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
15160 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
15170 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
15180 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
15190 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
151a0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
151b0 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
151c0 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
151d0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
151e0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
151f0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
15200 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
15210 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
15220 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
15230 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
15240 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
15250 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
15260 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
15270 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
15280 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
15290 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
152a0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
152b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
152c0 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
152d0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
152e0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
152f0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
15300 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
15310 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
15320 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
15330 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
15340 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
15350 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
15360 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
15370 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
15380 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
15390 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
153a0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
153b0 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
153c0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
153d0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
153e0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
153f0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
15400 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
15410 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
15420 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
15430 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
15440 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
15450 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
15460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
15470 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
15480 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
15490 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
154a0 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
154b0 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
154c0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
154d0 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
154e0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
154f0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
15500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15510 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
15520 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
15530 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
15540 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
15550 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
15560 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
15570 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
15580 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
15590 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
155a0 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
155b0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
155c0 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
155d0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
155e0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
155f0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
15600 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
15610 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
15620 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
15630 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
15640 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
15650 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
15660 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
15670 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
15680 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15690 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
156a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
156b0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
156c0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
156d0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
156e0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
156f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
15700 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
15710 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
15720 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
15730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15740 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
15750 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
15760 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
15770 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
15780 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
15790 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
157a0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
157b0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
157c0 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
157d0 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
157e0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
157f0 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
15800 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
15810 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
15820 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
15830 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
15840 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
15850 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
15860 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15870 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
15880 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
15890 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
158a0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
158b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
158c0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
158d0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
158e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
158f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
15900 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
15910 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
15920 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
15930 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
15940 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
15950 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
15960 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
15970 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
15980 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
15990 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
159a0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
159b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
159c0 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
159d0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
159e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
159f0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
15a00 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
15a10 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
15a20 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
15a30 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
15a40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15a50 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
15a60 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
15a70 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
15a80 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
15a90 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
15aa0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
15ab0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
15ac0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
15ad0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
15ae0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
15af0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
15b00 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
15b10 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
15b20 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
15b30 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
15b40 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
15b50 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
15b60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15b70 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
15b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15b90 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
15ba0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15bb0 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
15bc0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15bd0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15be0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15bf0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
15c00 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15c10 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15c20 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
15c30 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
15c40 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
15c50 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
15c60 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
15c70 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
15c80 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
15c90 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
15ca0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
15cb0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
15cc0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
15cd0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15ce0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15cf0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
15d00 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
15d10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15d20 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
15d30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15d40 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
15d50 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
15d60 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
15d70 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
15d80 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
15d90 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
15da0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
15db0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
15dc0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
15dd0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
15de0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15df0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
15e00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15e10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15e20 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
15e30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
15e40 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
15e50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15e60 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
15e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15e80 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
15e90 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15ea0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
15eb0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15ec0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15ed0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
15ee0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
15ef0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15f00 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15f10 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
15f20 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
15f30 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
15f40 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
15f50 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
15f60 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
15f70 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
15f80 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
15f90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
15fa0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
15fb0 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
15fc0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
15fd0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
15fe0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
15ff0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
16000 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
16010 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
16020 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
16030 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
16040 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
16050 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
16060 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
16070 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
16080 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16090 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
160a0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
160b0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
160c0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
160d0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
160e0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
160f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
16100 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
16110 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
16120 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16130 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
16140 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
16150 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
16170 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
16180 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16190 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
161a0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
161b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
161c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
161d0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
161e0 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
161f0 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
16200 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16210 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
16220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
16230 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
16240 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
16250 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
16260 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
16270 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
16280 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
16290 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
162a0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
162b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
162c0 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
162d0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
162e0 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
162f0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
16300 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
16310 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16320 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
16330 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
16340 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
16350 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
16360 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
16370 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
16380 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
16390 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
163a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
163b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
163c0 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
163d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
163e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
163f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16400 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
16410 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16420 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
16430 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
16440 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
16450 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
16460 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
16470 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
16480 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
16490 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
164a0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
164b0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
164c0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
164d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
164e0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
164f0 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
16500 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16510 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
16520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16530 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
16540 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16550 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16560 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
16570 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16580 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
16590 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
165a0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
165b0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
165c0 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
165d0 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
165e0 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
165f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
16600 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
16610 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
16620 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16630 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
16640 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
16650 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
16660 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16670 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16680 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
16690 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
166a0 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
166b0 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
166c0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
166d0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
166e0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
166f0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
16700 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
16710 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
16720 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
16730 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
16740 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
16750 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
16760 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
16770 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
16780 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
16790 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
167a0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
167b0 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
167c0 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
167d0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
167e0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
167f0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
16800 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
16810 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
16820 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
16830 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
16840 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
16850 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
16860 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
16870 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
16880 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
16890 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
168a0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
168b0 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
168c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
168d0 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
168e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
168f0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
16900 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
16910 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
16920 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
16930 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
16940 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
16950 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
16960 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
16970 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
16980 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
16990 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
169a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
169b0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
169c0 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
169d0 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
169e0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
169f0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
16a00 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
16a10 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
16a20 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
16a30 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
16a40 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
16a50 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
16a60 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
16a70 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
16a80 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
16a90 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
16aa0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
16ab0 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
16ac0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
16ad0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
16ae0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
16af0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
16b00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16b10 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
16b20 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
16b30 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
16b40 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
16b50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16b60 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
16b70 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
16b80 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
16b90 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16ba0 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
16bb0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
16bc0 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
16bd0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
16be0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
16bf0 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
16c00 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16c10 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
16c20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
16c30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16c40 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
16c50 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
16c60 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
16c70 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
16c80 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
16c90 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
16ca0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16cb0 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
16cc0 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
16cd0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
16ce0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
16cf0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16d00 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
16d10 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16d20 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
16d30 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
16d40 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
16d50 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
16d60 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
16d70 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
16d80 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
16d90 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
16da0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
16db0 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
16dc0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
16dd0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16de0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
16df0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
16e00 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
16e10 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
16e20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
16e30 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
16e40 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
16e50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16e60 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
16e70 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
16e80 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
16e90 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
16ea0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16eb0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16ec0 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
16ed0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16ee0 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
16ef0 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
16f00 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
16f10 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
16f20 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16f30 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
16f40 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
16f50 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
16f60 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
16f70 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
16f80 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16f90 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
16fa0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
16fb0 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
16fc0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
16fd0 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
16fe0 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
16ff0 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
17000 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
17010 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
17020 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
17030 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
17040 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
17050 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
17060 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
17070 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
17080 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
17090 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
170a0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
170b0 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
170c0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
170d0 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
170e0 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
170f0 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
17100 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
17110 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
17120 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
17130 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
17140 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
17150 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
17160 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
17170 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
17180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17190 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
171a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
171b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
171c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
171d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
171e0 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
171f0 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
17200 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
17210 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
17220 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
17230 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
17240 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
17250 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
17260 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
17270 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
17280 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17290 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
172a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
172b0 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
172c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
172d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
172e0 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
172f0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
17300 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
17310 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
17320 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
17330 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
17340 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
17350 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
17360 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
17370 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
17380 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
17390 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
173a0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
173b0 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
173c0 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
173d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
173e0 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
173f0 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
17400 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
17410 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
17420 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
17430 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
17440 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
17450 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
17460 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
17470 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17480 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
17490 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
174a0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
174b0 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
174c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
174d0 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
174e0 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
174f0 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
17500 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
17510 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
17520 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
17530 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
17540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
17550 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
17560 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
17570 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
17580 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
17590 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
175a0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
175b0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
175c0 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
175d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
175e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
175f0 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
17600 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
17610 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
17620 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
17630 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
17640 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
17650 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17660 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
17670 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
17680 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
17690 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
176a0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
176b0 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
176c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
176d0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
176e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
176f0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
17700 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
17710 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
17720 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
17730 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
17740 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
17750 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
17760 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
17770 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
17780 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
17790 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
177a0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
177b0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
177c0 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
177d0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
177e0 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
177f0 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
17800 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
17810 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
17820 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
17830 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
17840 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
17850 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
17860 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
17870 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
17880 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
17890 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
178a0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
178b0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
178c0 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
178d0 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
178e0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
178f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
17900 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
17910 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
17920 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
17930 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
17940 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
17950 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
17960 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
17970 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
17980 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
17990 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
179a0 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
179b0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
179c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
179d0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
179e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
179f0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17a00 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
17a10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
17a20 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
17a30 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
17a40 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
17a50 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
17a60 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
17a70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
17a80 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
17a90 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
17aa0 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
17ab0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17ac0 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
17ad0 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
17ae0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
17af0 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
17b00 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
17b10 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
17b20 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
17b30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17b40 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
17b50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17b60 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
17b70 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17b80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17b90 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
17ba0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
17bb0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
17bc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17bd0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
17be0 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
17bf0 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
17c00 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
17c10 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
17c20 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
17c30 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
17c40 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
17c50 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
17c60 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
17c70 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
17c80 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
17c90 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
17ca0 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
17cb0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
17cc0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
17cd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17ce0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17cf0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
17d00 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17d10 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
17d20 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17d30 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17d40 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
17d50 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
17d60 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
17d70 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
17d80 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
17d90 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
17da0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
17db0 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
17dc0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
17dd0 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
17de0 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
17df0 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
17e00 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
17e10 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
17e20 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
17e30 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
17e40 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
17e50 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
17e60 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
17e70 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
17e80 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
17e90 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
17ea0 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
17eb0 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
17ec0 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
17ed0 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
17ee0 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
17ef0 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
17f00 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
17f10 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
17f20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17f30 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
17f40 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17f50 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
17f60 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
17f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17f80 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
17f90 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17fa0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17fb0 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
17fc0 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
17fd0 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
17fe0 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
17ff0 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
18000 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
18010 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
18020 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
18030 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
18040 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
18050 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
18060 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
18070 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
18080 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
18090 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
180a0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
180b0 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
180c0 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
180d0 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
180e0 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
180f0 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
18100 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
18110 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
18120 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
18130 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
18140 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
18150 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
18160 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
18170 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
18180 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
18190 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
181a0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
181b0 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
181c0 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
181d0 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
181e0 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
181f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
18200 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
18210 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53  NFIG_SORTERREF_S
18220 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
18230 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45  ITE_CONFIG_SORTE
18240 52 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  RREF_SIZE.** <dd
18250 3e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  >The SQLITE_CONF
18260 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a  IG_SORTERREF_SIZ
18270 45 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73  E option accepts
18280 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
18290 74 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28  ter.** of type (
182a0 69 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76  int) - the new v
182b0 61 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74  alue of the sort
182c0 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a  er-reference siz
182d0 65 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20  e threshold..** 
182e0 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51  Usually, when SQ
182f0 4c 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74  Lite uses an ext
18300 65 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72  ernal sort to or
18310 64 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f  der records acco
18320 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f  rding.** to an O
18330 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20  RDER BY clause, 
18340 61 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69  all fields requi
18350 72 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65  red by the calle
18360 72 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e  r are present in
18370 20 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72   the.** sorted r
18380 65 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c  ecords. However,
18390 20 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   if SQLite deter
183a0 6d 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74  mines based on t
183b0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
183c0 0a 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63  .** of a table c
183d0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76  olumn that its v
183e0 61 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79  alues are likely
183f0 20 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67   to be very larg
18400 65 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68  e - larger.** th
18410 61 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65  an the configure
18420 64 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e  d sorter-referen
18430 63 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c  ce size threshol
18440 64 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72  d - then a refer
18450 65 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65  ence.** is store
18460 64 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64  d in each sorted
18470 20 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20   record and the 
18480 72 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20  required column 
18490 76 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a  values loaded.**
184a0 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
184b0 73 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72  se as records ar
184c0 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f  e returned in so
184d0 72 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20  rted order. The 
184e0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
184f0 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e   for this option
18500 20 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65   is to never use
18510 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69   this optimizati
18520 6f 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61  on. Specifying a
18530 20 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61   .** negative va
18540 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74  lue for this opt
18550 69 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65  ion restores the
18560 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
18570 75 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  ur..** This opti
18580 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
18590 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
185a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
185b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
185c0 4e 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46  NABLE_SORTER_REF
185d0 45 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65  ERENCES] compile
185e0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
185f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
18600 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a  FIG_MEMDB_MAXSIZ
18610 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
18620 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d  E_CONFIG_MEMDB_M
18630 41 58 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68  AXSIZE.** <dd>Th
18640 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18650 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20 6f 70  MEMDB_MAXSIZE op
18660 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73  tion accepts a s
18670 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a  ingle parameter.
18680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36  ** [sqlite3_int6
18690 34 5d 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  4] parameter whi
186a0 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
186b0 74 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 66  t maximum size f
186c0 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 0a  or an in-memory.
186d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 72 65 61  ** database crea
186e0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
186f0 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29  e3_deserialize()
18700 5d 2e 20 20 54 68 69 73 20 64 65 66 61 75 6c 74  ].  This default
18710 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 73 69 7a 65   maximum.** size
18720 20 63 61 6e 20 62 65 20 61 64 6a 75 73 74 65 64   can be adjusted
18730 20 75 70 20 6f 72 20 64 6f 77 6e 20 66 6f 72 20   up or down for 
18740 69 6e 64 69 76 69 64 75 61 6c 20 64 61 74 61 62  individual datab
18750 61 73 65 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  ases using the.*
18760 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
18770 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 5b 73 71 6c  SIZE_LIMIT] [sql
18780 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
18790 6c 7c 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 5d 2e  l|file-control].
187a0 20 20 49 66 20 74 68 69 73 0a 2a 2a 20 63 6f 6e    If this.** con
187b0 66 69 67 75 72 61 74 69 6f 6e 20 73 65 74 74 69  figuration setti
187c0 6e 67 20 69 73 20 6e 65 76 65 72 20 75 73 65 64  ng is never used
187d0 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  , then the defau
187e0 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 64 65  lt maximum is de
187f0 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
18800 68 65 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 42  he [SQLITE_MEMDB
18810 5f 44 45 46 41 55 4c 54 5f 4d 41 58 53 49 5a 45  _DEFAULT_MAXSIZE
18820 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
18830 70 74 69 6f 6e 2e 20 20 49 66 20 74 68 61 74 0a  ption.  If that.
18840 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
18850 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 73 65  option is not se
18860 74 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  t, then the defa
18870 75 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 31  ult maximum is 1
18880 30 37 33 37 34 31 38 32 34 2e 0a 2a 2a 20 3c 2f  073741824..** </
18890 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
188a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
188b0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
188c0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
188d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
188e0 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
188f0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
18900 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18910 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
18920 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
18930 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18940 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
18950 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
18960 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18970 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18980 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
18990 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
189a0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
189b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
189c0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
189d0 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65    6  /* No longe
189e0 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
189f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18a00 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
18a10 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
18a20 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
18a30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18a40 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
18a50 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
18a60 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
18a70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18a80 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
18a90 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
18aa0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
18ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
18ac0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
18ad0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
18ae0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18af0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18b00 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
18b10 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
18b20 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
18b30 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
18b40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
18b50 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
18b60 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
18b70 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
18b80 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
18b90 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
18ba0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18bc0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
18bd0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
18be0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18bf0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
18c00 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
18c10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18c20 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
18c30 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
18c40 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
18c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
18c60 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
18c70 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
18c80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18c90 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
18ca0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
18cb0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
18cc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18cd0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
18ce0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
18cf0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
18d00 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18d10 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
18d20 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
18d30 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
18d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18d50 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
18d60 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
18d70 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
18d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18d90 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
18da0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
18db0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
18dc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18dd0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
18de0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
18df0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
18e00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e10 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
18e20 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
18e30 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
18e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18e50 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
18e60 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
18e70 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
18e80 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
18e90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
18ea0 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
18eb0 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
18ec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ed0 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
18ee0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20  ALLOC        27 
18ef0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
18f00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18f10 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53  NFIG_SORTERREF_S
18f20 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20  IZE      28  /* 
18f30 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
18f40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18f50 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45  IG_MEMDB_MAXSIZE
18f60 20 20 20 20 20 20 20 32 39 20 20 2f 2a 20 73 71         29  /* sq
18f70 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a  lite3_int64 */..
18f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18f90 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
18fa0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
18fb0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
18fc0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
18fd0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
18fe0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
18ff0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
19000 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
19010 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
19020 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
19030 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
19040 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
19050 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
19060 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
19070 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
19080 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
19090 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
190a0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
190b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
190c0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
190d0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
190e0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
190f0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
19100 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
19110 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
19120 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
19130 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
19140 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
19150 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
19160 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
19170 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
19180 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
19190 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
191a0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
191b0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
191c0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
191d0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
191e0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
191f0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
19200 49 44 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IDE]].** <dt>SQL
19210 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
19220 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
19230 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19240 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
19250 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
19260 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
19270 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
19280 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
19290 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
192a0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
192b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
192c0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
192d0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
192e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
192f0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
19300 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
19310 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
19320 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
19330 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
19340 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
19350 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
19360 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
19370 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
19380 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
19390 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
193a0 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
193b0 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
193c0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
193d0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
193e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
193f0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
19400 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
19410 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
19420 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
19430 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
19440 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
19450 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
19460 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
19470 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
19480 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
19490 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
194a0 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
194b0 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
194c0 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
194d0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
194e0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
194f0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
19500 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
19510 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
19520 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
19530 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
19540 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
19550 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
19560 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
19570 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
19580 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
19590 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
195a0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
195b0 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
195c0 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
195d0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
195e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
195f0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
19600 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
19610 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
19620 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
19630 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
19640 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
19650 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
19660 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
19670 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
19680 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
19690 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
196a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
196b0 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
196c0 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
196d0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
196e0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
196f0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
19700 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
19710 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
19720 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
19730 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
19740 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
19750 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
19760 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
19770 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
19780 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
19790 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
197a0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
197b0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
197c0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
197d0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
197e0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
197f0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
19800 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
19810 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
19820 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
19830 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
19840 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
19850 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19860 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19870 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19880 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
19890 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
198a0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
198b0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
198c0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
198d0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
198e0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
198f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19900 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
19910 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
19920 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
19930 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
19940 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
19950 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
19960 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
19970 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19980 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19990 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
199a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
199b0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
199c0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
199d0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
199e0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
199f0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
19a00 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19a10 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 5d 5d  ENABLE_TRIGGER]]
19a20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19a30 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
19a40 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
19a50 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19a60 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
19a70 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
19a80 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
19a90 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
19aa0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
19ab0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
19ac0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
19ad0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
19ae0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
19af0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
19b00 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
19b10 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
19b20 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
19b30 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
19b40 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
19b50 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
19b60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
19b70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
19b80 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
19b90 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
19ba0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
19bb0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
19bc0 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
19bd0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
19be0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
19bf0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
19c00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
19c10 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
19c20 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
19c30 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
19c40 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
19c50 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
19c60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
19c70 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19c80 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
19c90 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ER]].** <dt>SQLI
19ca0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19cb0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
19cc0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
19cd0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
19ce0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
19cf0 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20   disable the.** 
19d00 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28  [fts3_tokenizer(
19d10 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  )] function whic
19d20 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  h is part of the
19d30 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d  .** [FTS3] full-
19d40 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69  text search engi
19d50 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a  ne extension..**
19d60 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
19d70 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19d80 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
19d90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19da0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
19db0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
19dc0 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
19dd0 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69  zer() or.** posi
19de0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66  tive to enable f
19df0 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
19e00 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
19e10 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
19e20 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  .** unchanged..*
19e30 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
19e40 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
19e50 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
19e60 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
19e70 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
19e80 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
19e90 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e  ether fts3_token
19ea0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
19eb0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
19ec0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
19ed0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
19ee0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
19ef0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
19f00 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
19f10 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
19f20 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
19f30 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
19f40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
19f50 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
19f60 44 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a  D_EXTENSION]].**
19f70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19f80 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
19f90 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a  _EXTENSION</dt>.
19fa0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
19fb0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
19fc0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
19fd0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
19fe0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
19ff0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e  .** interface in
1a000 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74  dependently of t
1a010 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
1a020 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  on()] SQL functi
1a030 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  on..** The [sqli
1a040 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
1a050 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49  extension()] API
1a060 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
1a070 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a  bles both the.**
1a080 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f   C-API [sqlite3_
1a090 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1a0a0 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  ] and the SQL fu
1a0b0 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74  nction [load_ext
1a0c0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68  ension()]..** Th
1a0d0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
1a0e0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
1a0f0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20  uments..** When 
1a100 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1a110 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72  nt to this inter
1a120 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20  face is 1, then 
1a130 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69  only the C-API i
1a140 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64  s.** enabled and
1a150 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
1a160 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c  n remains disabl
1a170 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  ed.  If the firs
1a180 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  t argument to.**
1a190 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1a1a0 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20  is 0, then both 
1a1b0 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68  the C-API and th
1a1c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
1a1d0 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20  re disabled..** 
1a1e0 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
1a1f0 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65  ument is -1, the
1a200 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65  n no changes are
1a210 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f   made to state o
1a220 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  f either the.** 
1a230 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c  C-API or the SQL
1a240 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
1a250 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a260 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
1a270 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
1a280 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
1a290 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
1a2a0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
1a2b0 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  r [sqlite3_load_
1a2c0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
1a2d0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73  erface.** is dis
1a2e0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
1a2f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
1a300 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
1a310 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a  d parameter may.
1a320 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ** be a NULL poi
1a330 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63  nter, in which c
1a340 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
1a350 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
1a360 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64  ted back..** </d
1a370 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
1a380 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
1a390 42 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  BNAME]] <dt>SQLI
1a3a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
1a3b0 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBNAME</dt>.** <
1a3c0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
1a3d0 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e   is used to chan
1a3e0 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ge the name of t
1a3f0 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61  he "main" databa
1a400 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e  se.** schema.  ^
1a410 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e  The sole argumen
1a420 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
1a430 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46  o a constant UTF
1a440 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63  8 string.** whic
1a450 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  h will become th
1a460 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d  e new schema nam
1a470 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  e in place of "m
1a480 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a  ain".  ^SQLite.*
1a490 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20  * does not make 
1a4a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65  a copy of the ne
1a4b0 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61  w main schema na
1a4c0 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68  me string, so th
1a4d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
1a4e0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
1a4f0 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  t the argument p
1a500 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20  assed into this 
1a510 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20  DBCONFIG option 
1a520 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  is unchanged.** 
1a530 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20  until after the 
1a540 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a550 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c  ion closes..** <
1a560 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
1a570 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
1a580 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 5d 5d 20  CKPT_ON_CLOSE]] 
1a590 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
1a5a0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
1a5b0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
1a5c0 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
1a5d0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
1a5e0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
1a5f0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
1a600 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
1a610 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
1a620 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
1a630 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
1a640 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
1a650 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
1a660 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
1a670 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
1a680 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
1a690 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
1a6a0 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
1a6b0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
1a6c0 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
1a6d0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
1a6e0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
1a6f0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
1a700 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1a710 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1a720 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
1a730 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70  s an integer - p
1a740 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62  ositive to disab
1a750 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
1a760 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
1a770 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
1a780 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
1a790 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74  , and negative t
1a7a0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
1a7b0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
1a7c0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
1a7d0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
1a7e0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
1a7f0 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
1a800 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
1a810 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
1a820 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
1a830 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
1a840 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
1a850 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
1a860 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
1a870 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
1a880 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
1a890 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a8a0 4e 41 42 4c 45 5f 51 50 53 47 5d 5d 20 3c 64 74  NABLE_QPSG]] <dt
1a8b0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1a8c0 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74  _ENABLE_QPSG</dt
1a8d0 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  >.** <dd>^(The S
1a8e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a8f0 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f  NABLE_QPSG optio
1a900 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
1a910 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
1a920 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  e [query planner
1a930 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61   stability guara
1a940 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57  ntee] (QPSG).  W
1a950 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20  hen the QPSG is 
1a960 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e  active,.** a sin
1a970 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74  gle SQL query st
1a980 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77  atement will alw
1a990 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
1a9a0 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72   algorithm regar
1a9b0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75  dless.** of valu
1a9c0 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  es of [bound par
1a9d0 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20  ameters].)^ The 
1a9e0 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f  QPSG disables so
1a9f0 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  me query optimiz
1aa00 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c  ations.** that l
1aa10 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65  ook at the value
1aa20 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d  s of bound param
1aa30 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e  eters, which can
1aa40 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69   make some queri
1aa50 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42  es.** slower.  B
1aa60 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20  ut the QPSG has 
1aa70 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66  the advantage of
1aa80 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c   more predictabl
1aa90 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74  e behavior.  Wit
1aaa0 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63  h.** the QPSG ac
1aab0 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c  tive, SQLite wil
1aac0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
1aad0 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e   same query plan
1aae0 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73   in the field as
1aaf0 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72  .** was used dur
1ab00 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74  ing testing in t
1ab10 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66  he lab..** The f
1ab20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1ab30 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
1ab40 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
1ab50 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
1ab60 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20  e .** the QPSG, 
1ab70 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
1ab80 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61  le QPSG, or nega
1ab90 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1aba0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
1abb0 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f  hanged. The seco
1abc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1abd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1abe0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1abf0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
1ac00 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
1ac10 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20  ate whether the 
1ac20 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64  QPSG is disabled
1ac30 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
1ac40 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
1ac50 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ll..** </dd>.**.
1ac60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
1ac70 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
1ac80 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1ac90 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45  CONFIG_TRIGGER_E
1aca0 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  QP</dt>.** <dd> 
1acb0 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
1acc0 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49  output of EXPLAI
1acd0 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d  N QUERY PLAN com
1ace0 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a  mands does not .
1acf0 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75  ** include outpu
1ad00 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74  t for any operat
1ad10 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62  ions performed b
1ad20 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  y trigger progra
1ad30 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69  ms. This.** opti
1ad40 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  on is used to se
1ad50 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20  t or clear (the 
1ad60 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20  default) a flag 
1ad70 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69  that governs thi
1ad80 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54  s.** behavior. T
1ad90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1ada0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1adb0 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  s operation is a
1adc0 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70  n integer -.** p
1add0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1ade0 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69  e output for tri
1adf0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f  gger programs, o
1ae00 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c  r zero to disabl
1ae10 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61  e it,.** or nega
1ae20 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1ae30 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
1ae40 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
1ae50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1ae60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1ae70 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1ae80 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a  ch is written .*
1ae90 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  * 0 or 1 to indi
1aea0 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74  cate whether out
1aeb0 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73  put-for-triggers
1aec0 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c   has been disabl
1aed0 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74  ed - 0 if .** it
1aee0 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64   is not disabled
1aef0 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a  , 1 if it is.  .
1af00 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
1af10 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
1af20 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 5d  _RESET_DATABASE]
1af30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  ] <dt>SQLITE_DBC
1af40 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1af50 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  BASE</dt>.** <dd
1af60 3e 20 53 65 74 20 74 68 65 20 53 51 4c 49 54 45  > Set the SQLITE
1af70 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1af80 44 41 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e  DATABASE flag an
1af90 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56  d then run.** [V
1afa0 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20  ACUUM] in order 
1afb0 74 6f 20 72 65 73 65 74 20 61 20 64 61 74 61 62  to reset a datab
1afc0 61 73 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65  ase back to an e
1afd0 6d 70 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mpty database.**
1afe0 20 77 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20   with no schema 
1aff0 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20  and no content. 
1b000 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  The following pr
1b010 6f 63 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e  ocess works even
1b020 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20   for.** a badly 
1b030 63 6f 72 72 75 70 74 65 64 20 64 61 74 61 62 61  corrupted databa
1b040 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e  se file:.** <ol>
1b050 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74 68 65 20  .** <li> If the 
1b060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b070 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20 6f 70 65  ion is newly ope
1b080 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72 65 20 69  ned, make sure i
1b090 74 20 68 61 73 20 72 65 61 64 20 74 68 65 0a 2a  t has read the.*
1b0a0 2a 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20  *      database 
1b0b0 73 63 68 65 6d 61 20 62 79 20 70 72 65 70 61 72  schema by prepar
1b0c0 69 6e 67 20 74 68 65 6e 20 64 69 73 63 61 72 64  ing then discard
1b0d0 69 6e 67 20 73 6f 6d 65 20 71 75 65 72 79 20 61  ing some query a
1b0e0 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a 20 20 20  gainst the.**   
1b0f0 20 20 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20     database, or 
1b100 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
1b110 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
1b120 61 64 61 74 61 28 29 2c 20 69 67 6e 6f 72 69 6e  adata(), ignorin
1b130 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 65 72  g any.**      er
1b140 72 6f 72 73 2e 20 20 54 68 69 73 20 73 74 65 70  rors.  This step
1b150 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61   is only necessa
1b160 72 79 20 69 66 20 74 68 65 20 61 70 70 6c 69 63  ry if the applic
1b170 61 74 69 6f 6e 20 64 65 73 69 72 65 73 20 74 6f  ation desires to
1b180 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20 20 74 68   keep.**      th
1b190 65 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41  e database in WA
1b1a0 4c 20 6d 6f 64 65 20 61 66 74 65 72 20 74 68 65  L mode after the
1b1b0 20 72 65 73 65 74 20 69 66 20 69 74 20 77 61 73   reset if it was
1b1c0 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20 62 65 66   in WAL mode bef
1b1d0 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  ore.**      the 
1b1e0 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69 3e  reset.  .** <li>
1b1f0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
1b200 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42  ig(db, SQLITE_DB
1b210 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1b220 41 42 41 53 45 2c 20 31 2c 20 30 29 3b 0a 2a 2a  ABASE, 1, 0);.**
1b230 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 65   <li> [sqlite3_e
1b240 78 65 63 5d 28 64 62 2c 20 22 5b 56 41 43 55 55  xec](db, "[VACUU
1b250 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  M]", 0, 0, 0);.*
1b260 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64  * <li> sqlite3_d
1b270 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c  b_config(db, SQL
1b280 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1b290 45 54 5f 44 41 54 41 42 41 53 45 2c 20 30 2c 20  ET_DATABASE, 0, 
1b2a0 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20  0);.** </ol>.** 
1b2b0 42 65 63 61 75 73 65 20 72 65 73 65 74 74 69 6e  Because resettin
1b2c0 67 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20  g a database is 
1b2d0 64 65 73 74 72 75 63 74 69 76 65 20 61 6e 64 20  destructive and 
1b2e0 69 72 72 65 76 65 72 73 69 62 6c 65 2c 20 74 68  irreversible, th
1b2f0 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20 72 65 71  e.** process req
1b300 75 69 72 65 73 20 74 68 65 20 75 73 65 20 6f 66  uires the use of
1b310 20 74 68 69 73 20 6f 62 73 63 75 72 65 20 41 50   this obscure AP
1b320 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c 65 20 73  I and multiple s
1b330 74 65 70 73 20 74 6f 20 68 65 6c 70 0a 2a 2a 20  teps to help.** 
1b340 65 6e 73 75 72 65 20 74 68 61 74 20 69 74 20 64  ensure that it d
1b350 6f 65 73 20 6e 6f 74 20 68 61 70 70 65 6e 20 62  oes not happen b
1b360 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a 2a  y accident..**.*
1b370 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1b380 46 49 47 5f 44 45 46 45 4e 53 49 56 45 5d 5d 20  FIG_DEFENSIVE]] 
1b390 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1b3a0 46 49 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f 64  FIG_DEFENSIVE</d
1b3b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  t>.** <dd>The SQ
1b3c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45  LITE_DBCONFIG_DE
1b3d0 46 45 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20 61  FENSIVE option a
1b3e0 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63  ctivates or deac
1b3f0 74 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22  tivates the.** "
1b400 64 65 66 65 6e 73 69 76 65 22 20 66 6c 61 67 20  defensive" flag 
1b410 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
1b420 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e  onnection.  When
1b430 20 74 68 65 20 64 65 66 65 6e 73 69 76 65 0a 2a   the defensive.*
1b440 2a 20 66 6c 61 67 20 69 73 20 65 6e 61 62 6c 65  * flag is enable
1b450 64 2c 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74  d, language feat
1b460 75 72 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 20  ures that allow 
1b470 6f 72 64 69 6e 61 72 79 20 53 51 4c 20 74 6f 20  ordinary SQL to 
1b480 0a 2a 2a 20 64 65 6c 69 62 65 72 61 74 65 6c 79  .** deliberately
1b490 20 63 6f 72 72 75 70 74 20 74 68 65 20 64 61 74   corrupt the dat
1b4a0 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 64  abase file are d
1b4b0 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 64 69  isabled.  The di
1b4c0 73 61 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75 72  sabled.** featur
1b4d0 65 73 20 69 6e 63 6c 75 64 65 20 62 75 74 20 61  es include but a
1b4e0 72 65 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74  re not limited t
1b4f0 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a  o the following:
1b500 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1b510 20 54 68 65 20 5b 50 52 41 47 4d 41 20 77 72 69   The [PRAGMA wri
1b520 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d  table_schema=ON]
1b530 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c   statement..** <
1b540 6c 69 3e 20 54 68 65 20 5b 50 52 41 47 4d 41 20  li> The [PRAGMA 
1b550 6a 6f 75 72 6e 61 6c 5f 6d 6f 64 65 3d 4f 46 46  journal_mode=OFF
1b560 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
1b570 3c 6c 69 3e 20 57 72 69 74 65 73 20 74 6f 20 74  <li> Writes to t
1b580 68 65 20 5b 73 71 6c 69 74 65 5f 64 62 70 61 67  he [sqlite_dbpag
1b590 65 5d 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e] virtual table
1b5a0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63 74  ..** <li> Direct
1b5b0 20 77 72 69 74 65 73 20 74 6f 20 5b 73 68 61 64   writes to [shad
1b5c0 6f 77 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 3c  ow tables]..** <
1b5d0 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  /ul>.** </dd>.**
1b5e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
1b5f0 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53  ONFIG_WRITABLE_S
1b600 43 48 45 4d 41 5d 5d 20 3c 64 74 3e 53 51 4c 49  CHEMA]] <dt>SQLI
1b610 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54  TE_DBCONFIG_WRIT
1b620 41 42 4c 45 5f 53 43 48 45 4d 41 3c 2f 64 74 3e  ABLE_SCHEMA</dt>
1b630 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
1b640 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54  TE_DBCONFIG_WRIT
1b650 41 42 4c 45 5f 53 43 48 45 4d 41 20 6f 70 74 69  ABLE_SCHEMA opti
1b660 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20  on activates or 
1b670 64 65 61 63 74 69 76 61 74 65 73 20 74 68 65 0a  deactivates the.
1b680 2a 2a 20 22 77 72 69 74 61 62 6c 65 5f 73 63 68  ** "writable_sch
1b690 65 6d 61 22 20 66 6c 61 67 2e 20 54 68 69 73 20  ema" flag. This 
1b6a0 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66  has the same eff
1b6b0 65 63 74 20 61 6e 64 20 69 73 20 6c 6f 67 69 63  ect and is logic
1b6c0 61 6c 6c 79 20 65 71 75 69 76 61 6c 65 6e 74 0a  ally equivalent.
1b6d0 2a 2a 20 74 6f 20 73 65 74 74 69 6e 67 20 5b 50  ** to setting [P
1b6e0 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73  RAGMA writable_s
1b6f0 63 68 65 6d 61 3d 4f 4e 5d 20 6f 72 20 5b 50 52  chema=ON] or [PR
1b700 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63  AGMA writable_sc
1b710 68 65 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a 20 54 68  hema=OFF]..** Th
1b720 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1b730 20 74 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67   to this setting
1b740 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
1b750 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
1b760 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 77 72 69  able .** the wri
1b770 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20 70 6f  table_schema, po
1b780 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
1b790 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61   writable_schema
1b7a0 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  , or negative to
1b7b0 0a 2a 2a 20 6c 65 61 76 65 20 74 68 65 20 73 65  .** leave the se
1b7c0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
1b7d0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1b7e0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
1b7f0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 74 65  er to an.** inte
1b800 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69  ger into which i
1b810 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
1b820 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
1b830 74 68 65 72 20 74 68 65 20 77 72 69 74 61 62 6c  ther the writabl
1b840 65 5f 73 63 68 65 6d 61 0a 2a 2a 20 69 73 20 65  e_schema.** is e
1b850 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
1b860 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ed following thi
1b870 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e  s call..** </dd>
1b880 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1b890 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1b8a0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20  NFIG_MAINDBNAME 
1b8b0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20             1000 
1b8c0 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a  /* const char* *
1b8d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b8e0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
1b8f0 49 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IDE             
1b900 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  1001 /* void* in
1b910 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
1b920 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1b930 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20  _ENABLE_FKEY    
1b940 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69         1002 /* i
1b950 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1b960 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1b970 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
1b980 52 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a  R        1003 /*
1b990 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1b9a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1b9b0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
1b9c0 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20  _TOKENIZER 1004 
1b9d0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1b9e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1b9f0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f  CONFIG_ENABLE_LO
1ba00 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30  AD_EXTENSION 100
1ba10 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  5 /* int int* */
1ba20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ba30 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54  DBCONFIG_NO_CKPT
1ba40 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31  _ON_CLOSE      1
1ba50 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  006 /* int int* 
1ba60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ba70 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1ba80 45 5f 51 50 53 47 20 20 20 20 20 20 20 20 20 20  E_QPSG          
1ba90 20 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74   1007 /* int int
1baa0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1bab0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49  ITE_DBCONFIG_TRI
1bac0 47 47 45 52 5f 45 51 50 20 20 20 20 20 20 20 20  GGER_EQP        
1bad0 20 20 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 69     1008 /* int i
1bae0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1baf0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52  QLITE_DBCONFIG_R
1bb00 45 53 45 54 5f 44 41 54 41 42 41 53 45 20 20 20  ESET_DATABASE   
1bb10 20 20 20 20 20 31 30 30 39 20 2f 2a 20 69 6e 74       1009 /* int
1bb20 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1bb30 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1bb40 5f 44 45 46 45 4e 53 49 56 45 20 20 20 20 20 20  _DEFENSIVE      
1bb50 20 20 20 20 20 20 20 31 30 31 30 20 2f 2a 20 69         1010 /* i
1bb60 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1bb70 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1bb80 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45  IG_WRITABLE_SCHE
1bb90 4d 41 20 20 20 20 20 20 20 31 30 31 31 20 2f 2a  MA       1011 /*
1bba0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1bbb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1bbc0 4e 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20  NFIG_MAX        
1bbd0 20 20 20 20 20 20 20 20 20 20 20 31 30 31 31 20             1011 
1bbe0 2f 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e  /* Largest DBCON
1bbf0 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  FIG */../*.** CA
1bc00 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
1bc10 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
1bc20 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
1bc30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1bc40 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1bc50 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
1bc60 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
1bc70 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
1bc80 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
1bc90 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1bca0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
1bcb0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
1bcc0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1bcd0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
1bce0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1bcf0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
1bd00 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1bd10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1bd20 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
1bd30 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
1bd40 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
1bd50 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
1bd60 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
1bd70 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1bd80 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
1bd90 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74  ry in most SQLit
1bda0 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74  e tables (except
1bdb0 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f   for [WITHOUT RO
1bdc0 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20  WID] tables).** 
1bdd0 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
1bde0 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
1bdf0 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
1be00 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
1be10 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
1be20 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
1be30 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
1be40 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
1be50 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
1be60 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
1be70 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
1be80 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
1be90 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
1bea0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
1beb0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
1bec0 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
1bed0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
1bee0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
1bef0 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
1bf00 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
1bf10 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
1bf20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
1bf30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61   ^The sqlite3_la
1bf40 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1bf50 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75  D) interface usu
1bf60 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
1bf70 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74   [rowid] of.** t
1bf80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
1bf90 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
1bfa0 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20  T] into a rowid 
1bfb0 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61  table or [virtua
1bfc0 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64  l table].** on d
1bfd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bfe0 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69  on D. ^Inserts i
1bff0 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  nto [WITHOUT ROW
1c000 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ID] tables are n
1c010 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20  ot.** recorded. 
1c020 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
1c030 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f  l [INSERT]s into
1c040 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61   rowid tables ha
1c050 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
1c060 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61   .** on the data
1c070 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c080 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  D, then sqlite3_
1c090 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1c0a0 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a  d(D) returns .**
1c0b0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20   zero..**.** As 
1c0c0 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65  well as being se
1c0d0 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  t automatically 
1c0e0 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65  as rows are inse
1c0f0 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61  rted into databa
1c100 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68  se.** tables, th
1c110 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1c120 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
1c130 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70  n may be set exp
1c140 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73  licitly by.** [s
1c150 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1c160 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
1c170 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75  **.** Some virtu
1c180 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
1c190 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53  ntations may INS
1c1a0 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f  ERT rows into ro
1c1b0 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a  wid tables as.**
1c1c0 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74   part of committ
1c1d0 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
1c1e0 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68  n (e.g. to flush
1c1f0 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65   data accumulate
1c200 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74  d in memory.** t
1c210 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73  o disk). In this
1c220 20 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74   case subsequent
1c230 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66   calls to this f
1c240 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74  unction return t
1c250 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f  he rowid.** asso
1c260 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73  ciated with thes
1c270 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52  e internal INSER
1c280 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68  T operations, wh
1c290 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a  ich leads to .**
1c2a0 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73   unintuitive res
1c2b0 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61  ults. Virtual ta
1c2c0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
1c2d0 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74  ons that do writ
1c2e0 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61  e to rowid.** ta
1c2f0 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79  bles in this way
1c300 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20   can avoid this 
1c310 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f  problem by resto
1c320 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
1c330 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75  l .** rowid valu
1c340 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
1c350 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1c360 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65  _rowid()] before
1c370 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63   returning .** c
1c380 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73  ontrol to the us
1c390 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  er..**.** ^(If a
1c3a0 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
1c3b0 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
1c3c0 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  er then this rou
1c3d0 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65  tine will .** re
1c3e0 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
1c3f0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
1c400 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
1c410 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a  the trigger is .
1c420 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65  ** running. Once
1c430 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1c440 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76  gram ends, the v
1c450 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
1c460 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
1c470 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
1c480 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
1c490 74 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20  the trigger was 
1c4a0 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  fired.)^.**.** ^
1c4b0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
1c4c0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
1c4d0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
1c4e0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
1c4f0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1c500 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
1c510 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
1c520 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
1c530 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
1c540 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
1c550 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
1c560 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
1c570 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
1c580 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
1c590 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
1c5a0 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
1c5b0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
1c5c0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
1c5d0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
1c5e0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
1c5f0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
1c600 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
1c610 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
1c620 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
1c630 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
1c640 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
1c650 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
1c660 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
1c670 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
1c680 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
1c690 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
1c6a0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
1c6b0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
1c6c0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
1c6d0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
1c6e0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
1c6f0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
1c700 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
1c710 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
1c720 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
1c730 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
1c740 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
1c750 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
1c760 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
1c770 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
1c780 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
1c790 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
1c7a0 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
1c7b0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
1c7c0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1c7d0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1c7e0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
1c7f0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
1c800 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
1c810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c820 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
1c830 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1c840 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
1c850 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
1c860 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
1c870 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
1c880 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
1c890 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1c8a0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1c8b0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1c8c0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
1c8d0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1c8e0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
1c8f0 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
1c900 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
1c910 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
1c920 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1c930 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
1c940 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
1c950 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1c960 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65  API3REF: Set the
1c970 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
1c980 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54  id value..** MET
1c990 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1c9a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
1c9b0 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
1c9c0 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f  owid(D, R) metho
1c9d0 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70  d allows the app
1c9e0 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73  lication to.** s
1c9f0 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  et the value ret
1ca00 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  urned by calling
1ca10 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1ca20 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f  sert_rowid(D) to
1ca30 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69   R .** without i
1ca40 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69  nserting a row i
1ca50 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
1ca60 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1ca70 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1ca80 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
1ca90 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
1caa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cab0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
1cac0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
1cad0 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
1cae0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1caf0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1cb00 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1cb10 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c  f rows modified,
1cb20 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20   inserted or.** 
1cb30 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
1cb40 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
1cb50 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
1cb60 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a  PDATE or DELETE.
1cb70 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  ** statement on 
1cb80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1cb90 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  nection specifie
1cba0 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61  d by the only pa
1cbb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65  rameter..** ^Exe
1cbc0 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
1cbd0 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
1cbe0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
1cbf0 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65  modify the value
1cc00 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
1cc10 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
1cc20 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67  *.** ^Only chang
1cc30 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79  es made directly
1cc40 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
1cc50 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1cc60 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a   statement are.*
1cc70 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61  * considered - a
1cc80 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
1cc90 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41   caused by [CREA
1cca0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
1ccb0 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72  ggers], .** [for
1ccc0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1ccd0 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63  ] or [REPLACE] c
1cce0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1ccf0 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75  tion are not cou
1cd00 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61  nted..** .** Cha
1cd10 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1cd20 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1cd30 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54  ted by .** [INST
1cd40 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c  EAD OF trigger |
1cd50 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
1cd60 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  gers] are not co
1cd70 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75  unted. ^The valu
1cd80 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  e .** returned b
1cd90 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1cda0 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  s() immediately 
1cdb0 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c  after an INSERT,
1cdc0 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44   UPDATE or .** D
1cdd0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1cde0 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73  run on a view is
1cdf0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e   always zero. On
1ce00 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
1ce10 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c  to real .** tabl
1ce20 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
1ce30 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65  **.** Things are
1ce40 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
1ce50 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33  d if the sqlite3
1ce60 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
1ce70 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74  ion is.** execut
1ce80 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67  ed while a trigg
1ce90 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75  er program is ru
1cea0 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20  nning. This may 
1ceb0 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a  happen if the.**
1cec0 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68   program uses th
1ced0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1cee0 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69   function], or i
1cef0 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c  f some other cal
1cf00 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1cf10 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65  n invokes sqlite
1cf20 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65  3_changes() dire
1cf30 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c  ctly. Essentiall
1cf40 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y:.** .** <ul>.*
1cf50 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72  *   <li> ^(Befor
1cf60 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69  e entering a tri
1cf70 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65  gger program the
1cf80 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1cf90 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c  by.**        sql
1cfa0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1cfb0 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64  unction is saved
1cfc0 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67  . After the trig
1cfd0 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20  ger program .** 
1cfe0 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73         has finis
1cff0 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61  hed, the origina
1d000 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f  l value is resto
1d010 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20  red.)^.** .**   
1d020 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20  <li> ^(Within a 
1d030 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1d040 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44  each INSERT, UPD
1d050 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a  ATE and DELETE .
1d060 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d  **        statem
1d070 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c  ent sets the val
1d080 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1d090 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1d0a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e   .**        upon
1d0b0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e   completion as n
1d0c0 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65  ormal. Of course
1d0d0 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c  , this value wil
1d0e0 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a  l not include .*
1d0f0 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61  *        any cha
1d100 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62  nges performed b
1d110 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20  y sub-triggers, 
1d120 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  as the sqlite3_c
1d130 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
1d140 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62      value will b
1d150 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74  e saved and rest
1d160 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20  ored after each 
1d170 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20  sub-trigger has 
1d180 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  run.)^.** </ul>.
1d190 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61  ** .** ^This mea
1d1a0 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63  ns that if the c
1d1b0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1d1c0 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61  ction (or simila
1d1d0 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79  r) is used.** by
1d1e0 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52   the first INSER
1d1f0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1d200 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
1d210 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
1d220 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  it .** returns t
1d230 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20  he value as set 
1d240 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67  when the calling
1d250 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e   statement began
1d260 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
1d270 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79  If it is used by
1d280 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73   the second or s
1d290 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73  ubsequent such s
1d2a0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1d2b0 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72  a trigger .** pr
1d2c0 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65  ogram, the value
1d2d0 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63   returned reflec
1d2e0 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ts the number of
1d2f0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62   rows modified b
1d300 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f  y the .** previo
1d310 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  us INSERT, UPDAT
1d320 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
1d330 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
1d340 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
1d350 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1d360 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1d370 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1d380 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1d390 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1d3a0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1d3b0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1d3c0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
1d3d0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
1d3e0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1d3f0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1d400 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a  **.** See also:.
1d410 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1d420 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
1d430 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
1d440 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20  terface.** <li> 
1d450 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  the [count_chang
1d460 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c  es pragma].** <l
1d470 69 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  i> the [changes(
1d480 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a  ) SQL function].
1d490 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74  ** <li> the [dat
1d4a0 61 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61  a_version pragma
1d4b0 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ].** </ul>.*/.in
1d4c0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
1d4d0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1d4e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
1d4f0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
1d500 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
1d510 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1d520 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1d530 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1d540 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
1d550 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
1d560 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
1d570 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
1d580 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
1d590 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
1d5a0 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
1d5b0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
1d5c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d5d0 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
1d5e0 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
1d5f0 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
1d600 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
1d610 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
1d620 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
1d630 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1d640 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
1d650 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
1d660 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1d670 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1d680 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
1d690 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
1d6a0 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
1d6b0 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
1d6c0 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
1d6d0 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
1d6e0 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
1d6f0 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
1d700 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
1d710 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
1d720 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1d730 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1d740 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
1d750 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
1d760 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1d770 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1d780 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1d790 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6f  (D)] interface o
1d7a0 6e 6c 79 20 72 65 70 6f 72 74 73 20 74 68 65 20  nly reports the 
1d7b0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 72 6f 77  number.** of row
1d7c0 73 20 74 68 61 74 20 63 68 61 6e 67 65 64 20 64  s that changed d
1d7d0 75 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  ue to SQL statem
1d7e0 65 6e 74 20 72 75 6e 20 61 67 61 69 6e 73 74 20  ent run against 
1d7f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
1d800 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 79 20 63  ection D.  Any c
1d810 68 61 6e 67 65 73 20 62 79 20 6f 74 68 65 72 20  hanges by other 
1d820 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d830 69 6f 6e 73 20 61 72 65 20 69 67 6e 6f 72 65 64  ions are ignored
1d840 2e 0a 2a 2a 20 54 6f 20 64 65 74 65 63 74 20 63  ..** To detect c
1d850 68 61 6e 67 65 73 20 61 67 61 69 6e 73 74 20 61  hanges against a
1d860 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 66   database file f
1d870 72 6f 6d 20 6f 74 68 65 72 20 64 61 74 61 62 61  rom other databa
1d880 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
1d890 73 20 75 73 65 20 74 68 65 20 5b 50 52 41 47 4d  s use the [PRAGM
1d8a0 41 20 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d 20  A data_version] 
1d8b0 63 6f 6d 6d 61 6e 64 20 6f 72 20 74 68 65 0a 2a  command or the.*
1d8c0 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
1d8d0 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b 66  DATA_VERSION] [f
1d8e0 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a  ile control]..**
1d8f0 20 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61   .** If a separa
1d900 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1d910 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1d920 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1d930 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1d940 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
1d950 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1d960 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1d970 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1d980 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1d990 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1d9a0 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  gful..**.** See 
1d9b0 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  also:.** <ul>.**
1d9c0 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69 74   <li> the [sqlit
1d9d0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
1d9e0 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20  terface.** <li> 
1d9f0 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  the [count_chang
1da00 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c  es pragma].** <l
1da10 69 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  i> the [changes(
1da20 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a  ) SQL function].
1da30 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74  ** <li> the [dat
1da40 61 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61  a_version pragma
1da50 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 53  ].** <li> the [S
1da60 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41  QLITE_FCNTL_DATA
1da70 5f 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20  _VERSION] [file 
1da80 63 6f 6e 74 72 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c  control].** </ul
1da90 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
1daa0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1dab0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1dac0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1dad0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1dae0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1daf0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1db00 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1db10 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1db20 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1db30 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1db40 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1db50 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1db60 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1db70 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1db80 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1db90 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1dba0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1dbb0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1dbc0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1dbd0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1dbe0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1dbf0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1dc00 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1dc10 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1dc20 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1dc30 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1dc40 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1dc50 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1dc60 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1dc70 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1dc80 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1dc90 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1dca0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1dcb0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1dcc0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1dcd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1dce0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1dcf0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1dd00 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1dd10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1dd20 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1dd30 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1dd40 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1dd50 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1dd60 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1dd70 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1dd80 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1dd90 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1dda0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1ddb0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1ddc0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1ddd0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1dde0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1ddf0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1de00 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1de10 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1de20 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1de30 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1de40 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1de50 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1de60 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1de70 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1de80 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1de90 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1dea0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1deb0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1dec0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1ded0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1dee0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1def0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1df00 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1df10 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1df20 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1df30 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1df40 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1df50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1df60 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1df70 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1df80 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1df90 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1dfa0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1dfb0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1dfc0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1dfd0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1dfe0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1dff0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1e000 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1e010 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1e020 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1e030 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1e040 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1e050 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1e060 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1e070 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1e080 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1e090 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1e0a0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1e0b0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1e0c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1e0d0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1e0e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1e0f0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1e100 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1e110 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1e120 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1e130 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1e140 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1e150 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1e160 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1e170 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1e180 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1e190 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f  l returns..*/.vo
1e1a0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1e1b0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1e1c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e1d0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1e1e0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1e1f0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1e200 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1e210 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1e220 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1e230 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1e240 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1e250 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1e260 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1e270 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1e280 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1e290 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1e2a0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1e2b0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1e2c0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1e2d0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1e2e0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1e2f0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1e300 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1e310 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1e320 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1e330 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1e340 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1e350 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1e360 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1e370 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1e380 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1e390 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1e3a0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1e3b0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1e3c0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1e3d0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1e3e0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1e3f0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1e400 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1e410 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1e420 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1e430 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1e440 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1e450 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1e460 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1e470 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1e480 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1e490 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1e4a0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1e4b0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1e4c0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1e4d0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1e4e0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1e4f0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1e500 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1e510 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1e520 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1e530 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1e540 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1e550 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1e560 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1e570 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1e580 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1e590 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1e5a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1e5b0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1e5c0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1e5d0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1e5e0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1e5f0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1e600 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1e610 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1e620 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1e630 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1e640 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1e650 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1e660 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1e670 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1e680 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1e690 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1e6a0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1e6b0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1e6c0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1e6d0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1e6e0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1e6f0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1e700 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1e710 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1e720 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1e730 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1e740 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1e750 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1e760 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1e770 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1e780 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1e790 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1e7a0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1e7b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1e7c0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1e7d0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1e7e0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1e7f0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1e800 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
1e810 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1e820 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1e830 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1e840 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
1e850 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
1e860 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
1e870 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
1e880 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
1e890 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
1e8a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
1e8b0 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
1e8c0 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
1e8d0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
1e8e0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
1e8f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1e900 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
1e910 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1e920 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
1e930 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
1e940 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
1e950 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
1e960 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
1e970 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1e980 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1e990 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1e9a0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1e9b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
1e9c0 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
1e9d0 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
1e9e0 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
1e9f0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
1ea00 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ea10 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1ea20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1ea30 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
1ea40 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
1ea50 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
1ea60 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
1ea70 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1ea80 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1ea90 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1eaa0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1eab0 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
1eac0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
1ead0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
1eae0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
1eaf0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
1eb00 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1eb10 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1eb20 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
1eb30 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1eb40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1eb50 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
1eb60 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
1eb70 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
1eb80 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
1eb90 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1eba0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
1ebb0 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
1ebc0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1ebd0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
1ebe0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
1ebf0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
1ec00 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
1ec10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1ec20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
1ec30 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ked previously f
1ec40 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
1ec50 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
1ec60 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
1ec70 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
1ec80 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
1ec90 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
1eca0 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
1ecb0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1ecc0 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
1ecd0 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   is returned.** 
1ece0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1ecf0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  on..** ^If the c
1ed00 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1ed10 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
1ed20 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
1ed30 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  * is made to acc
1ed40 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1ed50 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
1ed60 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
1ed70 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
1ed80 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
1ed90 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
1eda0 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
1edb0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
1edc0 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
1edd0 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
1ede0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
1edf0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
1ee00 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
1ee10 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
1ee20 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
1ee30 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
1ee40 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
1ee50 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68  E_BUSY].** to th
1ee60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
1ee70 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1ee80 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68  g the .** busy h
1ee90 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1eea0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1eeb0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1eec0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1eed0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1eee0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1eef0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1ef00 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1ef10 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1ef20 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1ef30 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1ef40 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1ef50 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1ef60 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1ef70 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1ef80 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1ef90 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1efa0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1efb0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1efc0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1efd0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1efe0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1eff0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1f000 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1f010 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1f020 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1f030 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1f040 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1f050 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1f060 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1f070 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1f080 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1f090 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1f0a0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1f0b0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1f0c0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1f0d0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1f0e0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1f0f0 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1f100 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1f110 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1f120 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1f130 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1f140 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1f150 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1f160 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
1f170 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
1f180 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1f190 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
1f1a0 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
1f1b0 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
1f1c0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1f1d0 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
1f1e0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
1f1f0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1f200 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20  imeout()].** or 
1f210 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47  evaluating [PRAG
1f220 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d  MA busy_timeout=
1f230 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74  N] will change t
1f240 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
1f250 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61  er and thus clea
1f260 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  r any previously
1f270 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65   set busy handle
1f280 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1f290 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1f2a0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1f2b0 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1f2c0 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1f2d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1f2e0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1f2f0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49  busy handler.  I
1f300 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a  n other words,.*
1f310 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1f320 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  er is not reentr
1f330 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ant.  Any such a
1f340 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1f350 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1f360 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1f370 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1f380 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1f390 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f3a0 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1f3b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f3c0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1f3d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1f3e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1f3f0 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1f400 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a  e3*,int(*)(void*
1f410 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f  ,int),void*);../
1f420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1f430 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1f440 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1f450 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1f460 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1f470 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1f480 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1f490 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1f4a0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1f4b0 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1f4c0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1f4d0 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1f4e0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1f4f0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1f500 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1f510 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1f520 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1f530 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1f540 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1f550 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1f560 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1f570 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1f580 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1f590 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1f5a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f5b0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1f5c0 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1f5d0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1f5e0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1f5f0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1f600 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1f610 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1f620 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1f630 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1f640 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1f650 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1f660 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1f670 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1f680 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1f690 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1f6a0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1f6b0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1f6c0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1f6d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1f6e0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1f6f0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1f700 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1f710 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1f720 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1f730 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1f740 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1f750 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69  sy_timeout].*/.i
1f760 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1f770 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1f780 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1f790 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1f7a0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1f7b0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1f7c0 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1f7d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1f7e0 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1f7f0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1f800 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1f810 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1f820 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1f830 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1f840 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1f850 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1f860 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1f870 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1f880 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1f890 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1f8a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1f8b0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1f8c0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1f8d0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1f8e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1f8f0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1f900 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1f910 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1f920 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1f930 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1f940 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1f950 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1f960 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1f970 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1f980 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1f990 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1f9a0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1f9b0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1f9c0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1f9d0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1f9e0 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1f9f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1fa00 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1fa10 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1fa20 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1fa30 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1fa40 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1fa50 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1fa60 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1fa70 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1fa80 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1fa90 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1faa0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1fab0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1fac0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1fad0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1fae0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1faf0 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1fb00 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1fb10 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1fb20 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1fb30 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1fb40 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1fb50 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1fb60 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1fb70 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1fb80 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1fb90 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1fba0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1fbb0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1fbc0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1fbd0 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1fbe0 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1fbf0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1fc00 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1fc10 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1fc20 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1fc30 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1fc40 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1fc50 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1fc60 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1fc70 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1fc80 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1fc90 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1fca0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1fcb0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1fcc0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1fcd0 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1fce0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1fcf0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1fd00 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1fd10 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1fd20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1fd30 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1fd40 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1fd50 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1fd60 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1fd70 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1fd80 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1fd90 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1fda0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1fdb0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1fdc0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1fdd0 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1fde0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1fdf0 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1fe00 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1fe10 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1fe20 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1fe30 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1fe40 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1fe50 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1fe60 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1fe70 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1fe80 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1fe90 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1fea0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1feb0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1fec0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1fed0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1fee0 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1fef0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1ff00 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1ff10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ff20 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1ff30 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1ff40 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1ff50 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1ff60 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1ff70 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1ff80 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1ff90 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1ffa0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1ffb0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1ffc0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1ffd0 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1ffe0 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1fff0 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
20000 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
20010 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
20020 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
20030 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
20040 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
20050 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
20060 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
20070 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
20080 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
20090 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
200a0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
200b0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
200c0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
200d0 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
200e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
200f0 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
20100 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
20110 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
20120 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
20130 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
20140 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
20150 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
20160 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
20170 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
20180 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20190 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
201a0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
201b0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
201c0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
201d0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
201e0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
201f0 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
20200 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
20210 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
20220 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
20230 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
20240 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
20250 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
20260 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
20270 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
20280 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
20290 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
202a0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
202b0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
202c0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
202d0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
202e0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
202f0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
20300 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
20310 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
20320 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
20330 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
20340 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
20350 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
20360 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
20370 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
20380 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
20390 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
203a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
203b0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
203c0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
203d0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
203e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
203f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
20400 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
20410 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
20420 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
20430 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
20440 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
20450 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
20460 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
20470 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
20480 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
20490 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
204a0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
204b0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
204c0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
204d0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
204e0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
204f0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
20500 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
20510 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
20520 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
20530 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
20540 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
20550 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
20560 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
20570 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
20580 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
20590 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
205a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
205b0 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
205c0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
205d0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
205e0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
205f0 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
20600 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
20610 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
20620 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
20630 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
20640 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
20650 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f  es understand mo
20660 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e  st of the common
20670 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
20680 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ons from.** the 
20690 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
206a0 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c   printf() .** pl
206b0 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  us some addition
206c0 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20  al non-standard 
206d0 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b  formats ([%q], [
206e0 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b  %Q], [%w], and [
206f0 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65  %z])..** See the
20700 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74   [built-in print
20710 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  f()] documentati
20720 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a  on for details..
20730 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20740 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
20750 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
20760 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
20770 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
20780 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
20790 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
207a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
207b0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
207c0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
207d0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
207e0 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
207f0 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
20800 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
20810 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
20820 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
20830 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
20840 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73  3_malloc64()] is
20850 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
20860 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
20870 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
20880 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
20890 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
208a0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
208b0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
208c0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
208d0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
208e0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
208f0 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
20900 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
20910 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
20920 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
20930 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
20940 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
20950 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
20960 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
20970 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
20980 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
20990 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
209a0 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
209b0 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
209c0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
209d0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
209e0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
209f0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
20a00 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
20a10 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
20a20 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
20a30 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
20a40 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
20a50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
20a60 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
20a70 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
20a80 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
20a90 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
20aa0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
20ab0 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
20ac0 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
20ad0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
20ae0 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
20af0 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
20b00 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
20b10 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
20b20 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
20b30 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
20b40 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
20b50 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
20b60 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
20b70 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
20b80 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
20b90 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
20ba0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
20bb0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
20bc0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
20bd0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
20be0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
20bf0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
20c00 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
20c10 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
20c20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
20c30 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
20c40 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
20c50 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
20c60 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
20c70 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
20c80 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
20c90 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
20ca0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
20cb0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
20cc0 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
20cd0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
20ce0 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
20cf0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
20d00 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
20d10 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c  See also:  [buil
20d20 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20  t-in printf()], 
20d30 5b 70 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75  [printf() SQL fu
20d40 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20  nction].*/.char 
20d50 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
20d60 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
20d70 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
20d80 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
20d90 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
20da0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
20db0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
20dc0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
20dd0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
20de0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
20df0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
20e00 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
20e10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
20e20 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
20e30 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
20e40 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
20e50 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
20e60 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
20e70 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
20e80 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
20e90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
20ea0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
20eb0 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
20ec0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
20ed0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
20ee0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
20ef0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
20f00 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
20f10 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
20f20 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
20f30 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
20f40 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
20f50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20f60 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
20f70 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
20f80 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
20f90 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
20fa0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
20fb0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
20fc0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
20fd0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
20fe0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
20ff0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
21000 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
21010 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
21020 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
21030 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
21040 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
21050 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
21060 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
21070 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
21080 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
21090 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
210a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
210b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
210c0 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
210d0 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
210e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
210f0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
21100 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
21110 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
21120 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
21130 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
21140 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
21150 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
21160 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
21170 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
21180 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
21190 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
211a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
211b0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
211c0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
211d0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
211e0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
211f0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
21200 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
21210 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
21220 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
21230 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
21240 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
21250 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
21260 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
21270 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
21280 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
21290 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
212a0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
212b0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
212c0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
212d0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
212e0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
212f0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
21300 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
21310 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
21320 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
21330 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
21340 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
21350 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
21360 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
21370 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
21380 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
21390 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
213a0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
213b0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
213c0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
213d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
213e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
213f0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
21400 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
21410 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
21420 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
21430 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
21440 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
21450 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
21460 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
21470 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
21480 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
21490 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
214a0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
214b0 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
214c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
214d0 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
214e0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
214f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21500 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
21510 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
21520 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
21530 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
21540 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
21550 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
21560 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
21570 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
21580 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
21590 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
215a0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
215b0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
215c0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
215d0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
215e0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
215f0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
21600 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
21610 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
21620 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
21630 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
21640 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
21650 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
21660 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
21670 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
21680 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
21690 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
216a0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
216b0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
216c0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
216d0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
216e0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
216f0 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
21700 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
21710 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
21720 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
21730 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
21740 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
21750 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
21760 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
21770 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
21780 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
21790 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
217a0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
217b0 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
217c0 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
217d0 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
217e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
217f0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
21800 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
21810 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
21820 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
21830 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21840 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
21850 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
21860 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
21870 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
21880 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
21890 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
218a0 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
218b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
218c0 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
218d0 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
218e0 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
218f0 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
21900 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
21910 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
21920 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
21930 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
21940 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
21950 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
21960 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
21970 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
21980 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
21990 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
219a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
219b0 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
219c0 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
219d0 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
219e0 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
219f0 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
21a00 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
21a10 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
21a20 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
21a30 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
21a40 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
21a50 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
21a60 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
21a70 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
21a80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
21a90 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
21aa0 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
21ab0 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
21ac0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
21ad0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
21ae0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
21af0 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
21b00 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
21b10 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
21b20 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
21b30 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
21b40 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
21b50 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
21b60 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
21b70 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
21b80 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
21b90 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
21ba0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
21bb0 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
21bc0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
21bd0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
21be0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
21bf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
21c00 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
21c10 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
21c20 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
21c30 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
21c40 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
21c50 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
21c60 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
21c70 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
21c80 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
21c90 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
21ca0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
21cb0 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
21cc0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
21cd0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
21ce0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
21cf0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
21d00 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
21d10 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
21d20 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
21d30 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
21d40 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
21d50 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
21d60 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
21d70 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
21d80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
21d90 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
21da0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
21db0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
21dc0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
21dd0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
21de0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
21df0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
21e00 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
21e10 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
21e20 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
21e30 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
21e40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
21e50 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
21e60 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
21e70 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
21e80 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
21e90 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
21ea0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
21eb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
21ec0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
21ed0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
21ee0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
21ef0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
21f00 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
21f10 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
21f20 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
21f30 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
21f40 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
21f50 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
21f60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
21f70 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
21f80 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
21f90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
21fa0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
21fb0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
21fc0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
21fd0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
21fe0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
21ff0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
22000 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
22010 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
22020 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
22030 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
22040 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
22050 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
22060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22070 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
22080 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
22090 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
220a0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
220b0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
220c0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
220d0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
220e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
220f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
22100 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
22110 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
22120 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
22130 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
22140 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
22150 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
22160 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
22170 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
22180 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
22190 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
221a0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
221b0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
221c0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
221d0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
221e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
221f0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
22200 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
22210 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
22220 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
22230 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
22240 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
22250 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
22260 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
22270 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
22280 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
22290 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
222a0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
222b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
222c0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
222d0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
222e0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
222f0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
22300 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
22310 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
22320 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
22330 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
22340 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
22350 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
22360 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
22370 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
22380 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
22390 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
223a0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
223b0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
223c0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
223d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
223e0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
223f0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
22400 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
22410 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
22420 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
22430 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
22440 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
22450 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
22460 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
22470 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
22480 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
22490 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
224a0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
224b0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
224c0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
224d0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
224e0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
224f0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
22500 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
22510 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
22520 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
22530 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
22540 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
22550 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
22560 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
22570 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
22580 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
22590 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
225a0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
225b0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
225c0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
225d0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
225e0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
225f0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
22600 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
22610 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
22620 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
22630 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
22640 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
22650 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
22660 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
22670 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
22680 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
22690 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
226a0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
226b0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
226c0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
226d0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
226e0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
226f0 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
22700 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
22710 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
22720 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
22730 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
22740 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
22750 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
22760 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
22770 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
22780 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
22790 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
227a0 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
227b0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
227c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
227d0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
227e0 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
227f0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
22800 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
22810 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
22820 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
22830 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
22840 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
22850 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
22860 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
22870 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
22880 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
22890 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
228a0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
228b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
228c0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
228d0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
228e0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
228f0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
22900 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
22910 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
22920 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
22930 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
22940 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20  HOD: sqlite3.** 
22950 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f  KEYWORDS: {autho
22960 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a  rizer callback}.
22970 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
22980 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
22990 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
229a0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
229b0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
229c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
229d0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
229e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
229f0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
22a00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
22a10 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
22a20 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
22a30 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
22a40 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
22a50 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
22a60 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
22a70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
22a80 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
22a90 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v3()], [sqlit
22aa0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
22ab0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22ac0 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e  e16_v2()],.** an
22ad0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
22ae0 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74  re16_v3()].  ^At
22af0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
22b00 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
22b10 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
22b20 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
22b30 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
22b40 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
22b50 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
22b60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22b70 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
22b80 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
22b90 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
22ba0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
22bb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22bc0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
22bd0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
22be0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
22bf0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
22c00 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
22c10 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
22c20 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
22c30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
22c40 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
22c50 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
22c60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
22c70 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
22c80 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
22c90 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
22ca0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
22cb0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
22cc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22cd0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
22ce0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
22cf0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
22d00 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
22d10 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
22d20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
22d30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22d40 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
22d50 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
22d60 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
22d70 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
22d80 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
22d90 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
22da0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
22db0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
22dc0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
22dd0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
22de0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
22df0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
22e00 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
22e10 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
22e20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
22e30 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
22e40 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
22e50 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
22e60 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
22e70 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
22e80 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
22e90 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
22ea0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
22eb0 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
22ec0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
22ed0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
22ee0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
22ef0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
22f00 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
22f10 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
22f20 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
22f30 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
22f40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
22f50 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
22f60 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
22f70 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
22f80 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
22f90 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
22fa0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
22fb0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
22fc0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
22fd0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
22fe0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
22ff0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
23000 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70  re either NULL p
23010 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d  ointers or zero-
23020 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
23030 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61  gs.** that conta
23040 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65  in additional de
23050 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
23060 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
23070 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c  horized..** Appl
23080 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c  ications must al
23090 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64  ways be prepared
230a0 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20   to encounter a 
230b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20  NULL pointer in 
230c0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68  any.** of the th
230d0 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ird through the 
230e0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
230f0 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   of the authoriz
23100 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ation callback..
23110 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
23120 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
23130 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
23140 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
23150 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
23160 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
23170 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
23180 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
23190 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
231a0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
231b0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
231c0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
231d0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
231e0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
231f0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
23200 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
23210 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
23220 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
23230 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
23240 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
23250 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
23260 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
23270 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
23280 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
23290 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  When a table is 
232a0 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20  referenced by a 
232b0 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20  [SELECT] but no 
232c0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72  column values ar
232d0 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66  e.** extracted f
232e0 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28  rom that table (
232f0 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61  for example in a
23300 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22   query like.** "
23310 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20  SELECT count(*) 
23320 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20  FROM tab") then 
23330 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  the [SQLITE_READ
23340 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  ] authorizer cal
23350 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f  lback.** is invo
23360 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61  ked once for tha
23370 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63  t table with a c
23380 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20  olumn name that 
23390 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
233a0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  ng..** ^If the a
233b0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
233c0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
233d0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
233e0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
233f0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
23400 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
23410 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
23420 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
23430 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
23440 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
23450 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
23460 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
23470 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
23480 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
23490 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
234a0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
234b0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
234c0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
234d0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
234e0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
234f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
23500 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
23510 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
23520 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
23530 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
23540 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
23550 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
23560 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
23570 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
23580 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
23590 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
235a0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
235b0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
235c0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
235d0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
235e0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
235f0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
23600 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
23610 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
23620 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
23630 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
23640 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
23650 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
23660 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
23670 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
23680 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
23690 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
236a0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
236b0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
236c0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
236d0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
236e0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
236f0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
23700 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
23710 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
23720 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
23730 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
23740 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
23750 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
23760 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
23770 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
23780 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
23790 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
237a0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
237b0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
237c0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
237d0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
237e0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
237f0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
23800 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
23810 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
23820 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
23830 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
23840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
23850 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
23860 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
23870 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
23880 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
23890 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
238a0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
238b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
238c0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
238d0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
238e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
238f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
23900 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
23910 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
23920 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
23930 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
23940 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
23950 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23960 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
23970 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
23980 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
23990 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
239a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
239b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
239c0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
239d0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
239e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
239f0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
23a00 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
23a10 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
23a20 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
23a30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
23a40 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
23a50 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
23a60 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
23a70 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
23a80 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
23a90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
23aa0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
23ab0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
23ac0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
23ad0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
23ae0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
23af0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
23b00 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
23b10 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
23b20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
23b30 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
23b40 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
23b50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
23b60 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
23b70 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
23b80 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
23b90 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
23ba0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
23bb0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
23bc0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
23bd0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
23be0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23bf0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
23c00 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
23c10 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
23c20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
23c30 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
23c40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
23c50 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
23c60 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
23c70 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
23c80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
23c90 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
23ca0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
23cb0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
23cc0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
23cd0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
23ce0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
23cf0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
23d00 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
23d10 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
23d20 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
23d30 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
23d40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
23d50 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
23d60 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
23d70 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
23d80 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
23d90 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
23da0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
23db0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
23dc0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
23dd0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
23de0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
23df0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
23e00 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
23e10 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
23e20 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
23e30 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
23e40 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
23e50 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
23e60 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
23e70 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
23e80 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
23e90 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
23ea0 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
23eb0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
23ec0 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
23ed0 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
23ee0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
23ef0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
23f00 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
23f10 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
23f20 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
23f30 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
23f40 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
23f50 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
23f60 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
23f70 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
23f80 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
23f90 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
23fa0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
23fb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
23fc0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
23fd0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
23fe0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
23ff0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
24000 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
24010 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
24020 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
24030 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
24040 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
24050 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
24060 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
24070 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
24080 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
24090 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
240a0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
240b0 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
240c0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
240d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
240e0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
240f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
24100 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
24110 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
24120 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
24130 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
24140 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
24150 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
24160 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
24170 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
24180 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
24190 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
241a0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
241b0 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
241c0 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
241d0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
241e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
241f0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
24200 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
24210 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
24220 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
24230 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
24240 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
24250 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
24260 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
24270 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
24280 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
24290 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
242a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
242b0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
242c0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
242d0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
242e0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
242f0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
24300 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
24310 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
24320 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
24330 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
24340 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
24350 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24360 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
24370 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
24380 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
24390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
243a0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
243b0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
243c0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
243d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
243e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
243f0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
24400 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
24410 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
24420 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
24440 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
24450 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
24460 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
24470 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
24480 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
24490 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
244a0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
244b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
244c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
244d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
244e0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
244f0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
24500 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
24510 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
24520 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
24530 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
24540 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
24550 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24560 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24570 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
24580 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
24590 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
245a0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
245b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
245c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
245d0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
245e0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
245f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
24600 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24610 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
24620 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
24630 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24640 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24650 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24660 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
24670 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
24680 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
24690 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
246a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
246b0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
246c0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
246d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
246e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
246f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24700 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
24710 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
24720 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
24730 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24750 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
24760 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
24770 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24780 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
247a0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
247b0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
247c0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
247d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
247e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
247f0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
24800 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
24810 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
24820 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24840 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
24850 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
24860 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
24870 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
24880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24890 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
248a0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
248b0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
248c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
248d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
248e0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
248f0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
24900 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
24910 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
24930 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
24940 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
24950 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
24960 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
24970 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
24980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24990 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
249a0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
249b0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
249c0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
249d0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
249e0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
249f0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
24a00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
24a10 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
24a20 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
24a30 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
24a40 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24a50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24a60 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
24a70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
24a80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24a90 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
24aa0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
24ab0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
24ac0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
24ad0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
24ae0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
24af0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24b00 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
24b10 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
24b20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
24b30 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
24b40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24b50 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
24b60 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
24b70 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
24b80 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24b90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24ba0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
24bb0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
24bc0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
24bd0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24be0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24bf0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
24c00 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
24c10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24c20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24c30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24c40 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
24c50 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
24c60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24c70 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
24c80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24c90 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
24ca0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
24cb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
24cc0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
24cd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24ce0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
24cf0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
24d00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
24d10 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
24d20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24d30 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
24d40 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
24d50 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
24d60 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
24d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
24d80 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
24d90 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
24da0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
24db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
24dc0 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
24dd0 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
24de0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
24df0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
24e00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
24e10 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
24e20 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
24e30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
24e40 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
24e50 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63  tines are deprec
24e60 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  ated. Use the [s
24e70 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24e80 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
24e90 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72  instead of the r
24ea0 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65  outines describe
24eb0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
24ec0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
24ed0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
24ee0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
24ef0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
24f00 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
24f10 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
24f20 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
24f30 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
24f40 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
24f50 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
24f60 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
24f70 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
24f80 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
24f90 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
24fa0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
24fb0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
24fc0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
24fd0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
24fe0 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
24ff0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
25000 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
25010 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
25020 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
25030 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
25040 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
25050 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
25060 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
25070 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
25080 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
25090 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
250a0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
250b0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
250c0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
250d0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
250e0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
250f0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
25100 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
25110 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
25120 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
25130 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
25140 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
25150 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
25160 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
25170 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
25180 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
25190 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
251a0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
251b0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
251c0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
251d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
251e0 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
251f0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
25200 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
25210 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
25220 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
25230 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
25240 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
25250 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
25260 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
25270 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
25280 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
25290 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
252a0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
252b0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
252c0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
252d0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
252e0 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
252f0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
25300 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
25310 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
25320 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
25330 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
25340 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
25350 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
25360 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
25370 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
25380 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
25390 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
253a0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
253b0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
253c0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 6e 76 6f   callback.  Invo
253d0 6b 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 5b  king.** either [
253e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
253f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   or [sqlite3_tra
25400 63 65 5f 76 32 28 29 5d 20 77 69 6c 6c 20 63 61  ce_v2()] will ca
25410 6e 63 65 6c 20 74 68 65 0a 2a 2a 20 70 72 6f 66  ncel the.** prof
25420 69 6c 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2f  ile callback..*/
25430 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
25440 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
25450 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
25460 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
25470 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
25480 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
25490 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
254a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
254b0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
254c0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
254d0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
254e0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
254f0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
25500 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
25510 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
25520 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
25530 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
25540 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
25550 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
25560 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
25570 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
25580 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
25590 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
255a0 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
255b0 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20 61 72  logic.  The M ar
255c0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
255d0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
255e0 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20 4f  ,M,X,P)] is an O
255f0 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
25600 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
25610 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
25620 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20  ing constants.  
25630 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
25640 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
25650 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
25660 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
25670 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  wing constants..
25680 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e  **.** New tracin
25690 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  g constants may 
256a0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
256b0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
256c0 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
256d0 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72  back has four ar
256e0 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61  guments: xCallba
256f0 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
25700 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
25710 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e  is one of the in
25720 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73  teger type codes
25730 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20   above..** ^The 
25740 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
25750 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
25760 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ext pointer pass
25770 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
25780 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
25790 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
257a0 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  e_v2()]..** The 
257b0 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
257c0 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
257d0 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
257e0 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
257f0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
25800 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c  E_TRACE_STMT]] <
25810 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
25820 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  STMT</dt>.** <dd
25830 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
25840 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20  E_STMT callback 
25850 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
25860 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
25870 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65  ment.** first be
25880 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  gins running and
25890 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68   possibly at oth
258a0 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20  er times during 
258b0 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e  the.** execution
258c0 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
258d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68   statement, such
258e0 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74   as at the start
258f0 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67   of each.** trig
25900 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20  ger subprogram. 
25910 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
25920 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
25930 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
25940 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
25950 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e X argument is 
25960 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
25970 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69  tring which.** i
25980 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64  s the unexpanded
25990 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65   SQL text of the
259a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
259b0 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  ent or an SQL co
259c0 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69  mment .** that i
259d0 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76  ndicates the inv
259e0 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69  ocation of a tri
259f0 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c  gger.  ^The call
25a00 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65  back can compute
25a10 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78  .** the same tex
25a20 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  t that would hav
25a30 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20  e been returned 
25a40 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  by the legacy [s
25a50 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a  qlite3_trace()].
25a60 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  ** interface by 
25a70 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75  using the X argu
25a80 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69  ment when X begi
25a90 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64  ns with "--" and
25aa0 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71   invoking.** [sq
25ab0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
25ac0 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65  ql(P)] otherwise
25ad0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
25ae0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d  _TRACE_PROFILE]]
25af0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
25b00 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a  E_PROFILE</dt>.*
25b10 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
25b20 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
25b30 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73  allback provides
25b40 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74   approximately t
25b50 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72  he same.** infor
25b60 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f  mation as is pro
25b70 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71  vided by the [sq
25b80 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
25b90 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54   callback..** ^T
25ba0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
25bb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25bc0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25bd0 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
25be0 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  * X argument poi
25bf0 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20  nts to a 64-bit 
25c00 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
25c10 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f   the estimated o
25c20 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  f.** the number 
25c30 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68  of nanosecond th
25c40 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
25c50 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
25c60 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53  o run..** ^The S
25c70 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
25c80 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ILE callback is 
25c90 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
25ca0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
25cb0 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  hes..**.** [[SQL
25cc0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20  ITE_TRACE_ROW]] 
25cd0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
25ce0 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ROW</dt>.** <dd
25cf0 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
25d00 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69  E_ROW callback i
25d10 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
25d20 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  er a prepared.**
25d30 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72   statement gener
25d40 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f  ates a single ro
25d50 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a  w of result.  .*
25d60 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
25d70 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
25d80 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
25d90 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
25da0 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
25db0 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a   is unused..**.*
25dc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
25dd0 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c  _CLOSE]] <dt>SQL
25de0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c  ITE_TRACE_CLOSE<
25df0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
25e00 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
25e10 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  SE callback is i
25e20 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61  nvoked when a da
25e30 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
25e40 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
25e50 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
25e60 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
25e70 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
25e80 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74  nnection] object
25e90 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72  .** and the X ar
25ea0 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64  gument is unused
25eb0 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
25ec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
25ed0 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78  CE_STMT       0x
25ee0 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
25ef0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
25f00 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20     0x02.#define 
25f10 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
25f20 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65          0x04.#de
25f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
25f40 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30  E_CLOSE      0x0
25f50 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
25f60 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f  F: SQL Trace Hoo
25f70 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  k.** METHOD: sql
25f80 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
25f90 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
25fa0 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,M,X,P) interf
25fb0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
25fc0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
25fd0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61  * function X aga
25fe0 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63  inst [database c
25ff0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73  onnection] D, us
26000 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73  ing property mas
26010 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65  k M.** and conte
26020 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e  xt pointer P.  ^
26030 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63  If the X callbac
26040 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20  k is.** NULL or 
26050 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73  if the M mask is
26060 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63   zero, then trac
26070 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ing is disabled.
26080 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d    The.** M argum
26090 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
260a0 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20  e bitwise OR-ed 
260b0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
260c0 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b  * zero or more [
260d0 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f  SQLITE_TRACE] co
260e0 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nstants..**.** ^
260f0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74  Each call to eit
26100 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63  her sqlite3_trac
26110 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
26120 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69  race_v2() overri
26130 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73  des .** (cancels
26140 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  ) any prior call
26150 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61  s to sqlite3_tra
26160 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
26170 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  trace_v2()..**.*
26180 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63  * ^The X callbac
26190 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
261a0 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65  never any of the
261b0 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69   events identifi
261c0 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d  ed by .** mask M
261d0 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e   occur.  ^The in
261e0 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c  teger return val
261f0 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c  ue from the call
26200 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c  back is currentl
26210 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68  y.** ignored, th
26220 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68  ough this may ch
26230 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72  ange in future r
26240 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61  eleases.  Callba
26250 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ck.** implementa
26260 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74  tions should ret
26270 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75  urn zero to ensu
26280 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74  re future compat
26290 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
262a0 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
262b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
262c0 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
262d0 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c   callback(T,C,P,
262e0 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
262f0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
26300 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   the [SQLITE_TRA
26310 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  CE].** constants
26320 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79   to indicate why
26330 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61   the callback wa
26340 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  s invoked..** ^T
26350 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
26360 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
26370 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a  ontext pointer..
26380 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
26390 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
263a0 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
263b0 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
263c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
263d0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69  te3_trace_v2() i
263e0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
263f0 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20  nded to replace 
26400 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
26410 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
26420 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b  3_trace()] and [
26430 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
26440 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63  )], both of whic
26450 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61  h.** are depreca
26460 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
26470 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20  te3_trace_v2(.  
26480 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69  sqlite3*,.  unsi
26490 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e  gned uMask,.  in
264a0 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e  t(*xCallback)(un
264b0 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69  signed,void*,voi
264c0 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  d*,void*),.  voi
264d0 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a  d *pCtx.);../*.*
264e0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
264f0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
26500 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
26510 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
26520 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
26530 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
26540 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
26550 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
26560 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
26570 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
26580 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
26590 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
265a0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
265b0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
265c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
265d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
265e0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
265f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26600 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
26610 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
26620 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
26630 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
26640 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
26650 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
26660 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
26670 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
26680 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
26690 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
266a0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
266b0 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
266c0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
266d0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
266e0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
266f0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
26700 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
26710 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
26720 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
26730 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
26740 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
26750 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
26760 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
26770 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
26780 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
26790 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
267a0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
267b0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
267c0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
267d0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
267e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
267f0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
26800 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
26810 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
26820 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
26830 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
26840 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
26850 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
26860 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
26870 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
26880 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
26890 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
268a0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
268b0 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
268c0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
268d0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
268e0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
268f0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
26900 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
26910 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
26920 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
26930 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
26940 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
26950 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
26960 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
26970 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
26980 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
26990 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
269a0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
269b0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
269c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
269d0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
269e0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
269f0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
26a00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26a10 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
26a20 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
26a30 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
26a40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26a50 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
26a60 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
26a70 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
26a80 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
26a90 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
26aa0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
26ab0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
26ac0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
26ad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
26ae0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
26af0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
26b00 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
26b10 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
26b20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
26b30 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
26b40 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
26b50 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
26b60 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
26b70 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
26b80 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
26b90 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
26ba0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
26bb0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
26bc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26bd0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
26be0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
26bf0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
26c00 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
26c10 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
26c20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
26c30 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
26c40 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
26c50 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
26c60 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
26c70 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
26c80 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
26c90 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
26ca0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
26cb0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
26cc0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
26cd0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
26ce0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
26cf0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
26d00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
26d10 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
26d20 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
26d30 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
26d40 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
26d50 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
26d60 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
26d70 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
26d80 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
26d90 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
26da0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
26db0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
26dc0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
26dd0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
26de0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
26df0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
26e00 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
26e10 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
26e20 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
26e30 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
26e40 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
26e50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
26e60 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
26e70 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
26e80 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
26e90 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
26ea0 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
26eb0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
26ec0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
26ed0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
26ee0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
26ef0 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
26f00 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
26f10 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
26f20 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
26f30 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
26f40 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
26f50 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
26f60 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
26f70 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
26f80 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
26f90 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
26fa0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
26fb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
26fc0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
26fd0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
26fe0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
26ff0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
27000 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
27010 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
27020 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
27030 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
27040 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
27050 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
27060 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
27070 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
27080 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
27090 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
270a0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
270b0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
270c0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
270d0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
270e0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
270f0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
27100 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
27110 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
27120 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
27130 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
27140 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
27150 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
27160 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
27170 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
27180 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
27190 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
271a0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
271b0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
271c0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
271d0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
271e0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
271f0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
27200 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27210 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
27220 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
27230 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
27240 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
27250 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
27260 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
27270 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
27280 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
27290 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
272a0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
272b0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
272c0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
272d0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
272e0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
272f0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
27300 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
27310 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
27320 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
27330 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
27340 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
27350 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
27360 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
27370 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
27380 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
27390 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
273a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
273b0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
273c0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
273d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
273e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
273f0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
27400 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
27410 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
27420 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
27430 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
27440 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
27450 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
27460 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
27470 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
27480 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
27490 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
274a0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
274b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
274c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
274d0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
274e0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
274f0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
27500 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
27510 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
27520 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
27530 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
27540 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
27550 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
27560 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
27570 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
27580 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
27590 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
275a0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
275b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
275c0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
275d0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
275e0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
275f0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
27600 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
27610 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
27620 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
27630 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
27640 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
27650 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
27660 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
27670 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
27680 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
27690 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
276a0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
276b0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
276c0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
276d0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
276e0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
276f0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
27700 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
27710 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
27720 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
27730 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
27740 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
27750 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
27760 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
27770 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
27780 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
27790 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
277a0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
277b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
277c0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
277d0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
277e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
277f0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
27800 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
27810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
27820 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
27830 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
27840 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
27850 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
27860 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
27870 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27880 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
27890 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
278a0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
278b0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
278c0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
278d0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
278e0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
278f0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
27900 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
27910 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
27920 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
27930 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
27940 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
27950 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
27960 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
27970 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
27980 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
27990 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
279a0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
279b0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
279c0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
279d0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
279e0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
279f0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
27a00 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
27a10 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
27a20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
27a30 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
27a40 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
27a50 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
27a60 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
27a70 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
27a80 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
27a90 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
27aa0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
27ab0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
27ac0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
27ad0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
27ae0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
27af0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
27b00 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
27b10 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
27b20 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
27b30 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
27b40 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
27b50 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
27b60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27b70 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
27b80 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
27b90 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
27ba0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
27bb0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
27bc0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
27bd0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
27be0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
27bf0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
27c00 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
27c10 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
27c20 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
27c30 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
27c40 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
27c50 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
27c60 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
27c70 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
27c80 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
27c90 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
27ca0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
27cb0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
27cc0 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
27cd0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
27ce0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
27cf0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
27d00 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
27d10 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
27d20 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
27d30 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
27d40 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
27d50 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 74  .** set in the t
27d60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
27d70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27d80 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
27d90 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
27da0 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
27db0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
27dc0 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
27dd0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
27de0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
27df0 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
27e00 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
27e10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
27e20 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ion..** URI file
27e30 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
27e40 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
27e50 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
27e60 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
27e70 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
27e80 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
27e90 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
27ea0 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
27eb0 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
27ec0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
27ed0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
27ee0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
27ef0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
27f00 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
27f10 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
27f20 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
27f30 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
27f40 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
27f50 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
27f60 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
27f70 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
27f80 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
27f90 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
27fa0 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
27fb0 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
27fc0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
27fd0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
27fe0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
27ff0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
28000 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
28010 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
28020 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
28030 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
28040 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
28050 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
28060 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
28070 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
28080 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
28090 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
280a0 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
280b0 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
280c0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
280d0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
280e0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
280f0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
28100 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
28110 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
28120 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
28130 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
28140 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
28150 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
28160 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
28170 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
28180 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
28190 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f  . .** ^(On windo
281a0 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
281b0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
281c0 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
281d0 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
281e0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
281f0 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  C:").)^.**.** [[
28200 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
28210 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
28220 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
28230 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
28240 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
28250 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
28260 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
28270 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
28280 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
28290 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
282a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
282b0 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73  * SQLite and its
282c0 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73   built-in [VFSes
282d0 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  ] interpret the.
282e0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  ** following que
282f0 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
28300 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
28310 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
28320 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
28330 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
28340 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
28350 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
28360 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
28370 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
28380 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
28390 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
283a0 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
283b0 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
283c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
283d0 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
283e0 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
283f0 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
28400 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
28410 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
28420 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
28430 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
28440 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
28450 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
28460 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
28470 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
28480 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
28490 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
284a0 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
284b0 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
284c0 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
284d0 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
284e0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
284f0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
28500 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
28510 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
28520 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
28530 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
28540 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
28550 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
28560 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
28570 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
28580 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
28590 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
285a0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
285b0 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
285c0 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
285d0 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
285e0 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
285f0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
28600 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
28610 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
28620 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
28630 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
28640 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
28650 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
28660 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
28670 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
28680 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
28690 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
286a0 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
286b0 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
286c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
286d0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
286e0 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
286f0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
28700 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
28710 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
28720 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
28730 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
28740 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
28750 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
28760 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
28770 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
28780 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
28790 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
287a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
287b0 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
287c0 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
287d0 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
287e0 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
287f0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
28800 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
28810 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
28820 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
28830 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
28840 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
28850 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
28860 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
28870 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
28880 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
28890 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
288a0 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
288b0 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
288c0 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
288d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
288e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
288f0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
28900 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
28910 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
28920 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
28930 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
28940 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
28950 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
28960 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
28970 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
28980 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
28990 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
289a0 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
289b0 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
289c0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
289d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
289e0 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
289f0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
28a00 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
28a10 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
28a20 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
28a30 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
28a40 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
28a50 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
28a60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
28a70 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
28a80 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
28a90 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
28aa0 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
28ab0 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
28ac0 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
28ad0 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
28ae0 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
28af0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
28b00 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
28b10 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
28b20 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  CACHE flag..**.*
28b30 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c  *  <li> <b>psow<
28b40 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70  /b>: ^The psow p
28b50 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74  arameter indicat
28b60 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  es whether or no
28b70 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
28b80 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
28b90 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
28ba0 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
28bb0 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
28bc0 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
28bd0 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
28be0 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
28bf0 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  s..**.**  <li> <
28c00 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54  b>nolock</b>: ^T
28c10 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65  he nolock parame
28c20 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
28c30 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28c40 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66  .**     which if
28c50 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69   set disables fi
28c60 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f  le locking in ro
28c70 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d  llback journal m
28c80 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20  odes.  This.**  
28c90 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72     is useful for
28ca0 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74   accessing a dat
28cb0 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73  abase on a files
28cc0 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20  ystem that does 
28cd0 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f  not.**     suppo
28ce0 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75  rt locking.  Cau
28cf0 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20  tion:  Database 
28d00 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74  corruption might
28d10 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a   result if two.*
28d20 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72  *     or more pr
28d30 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f  ocesses write to
28d40 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
28d50 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f  se and any one o
28d60 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70  f those.**     p
28d70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f  rocesses uses no
28d80 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c  lock=1..**.**  <
28d90 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65  li> <b>immutable
28da0 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74  </b>: ^The immut
28db0 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69  able parameter i
28dc0 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
28dd0 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74  y.**     paramet
28de0 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  er that indicate
28df0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
28e00 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72  ase file is stor
28e10 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61  ed on.**     rea
28e20 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e  d-only media.  ^
28e30 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69  When immutable i
28e40 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73  s set, SQLite as
28e50 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
28e60 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66  *     database f
28e70 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  ile cannot be ch
28e80 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61  anged, even by a
28e90 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69   process with hi
28ea0 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76  gher.**     priv
28eb0 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68  ilege, and so th
28ec0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
28ed0 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61  ened read-only a
28ee0 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a  nd all locking.*
28ef0 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65  *     and change
28f00 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69   detection is di
28f10 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e  sabled.  Caution
28f20 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d  : Setting the im
28f30 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70  mutable.**     p
28f40 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74  roperty on a dat
28f50 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20  abase file that 
28f60 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61  does in fact cha
28f70 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a  nge can result.*
28f80 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65  *     in incorre
28f90 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ct query results
28fa0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
28fb0 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e  CORRUPT] errors.
28fc0 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f  .**     See also
28fd0 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  : [SQLITE_IOCAP_
28fe0 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20  IMMUTABLE]..**  
28ff0 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a       .** </ul>.*
29000 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
29010 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
29020 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
29030 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
29040 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
29050 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
29060 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
29070 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
29080 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
29090 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
290a0 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
290b0 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
290c0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
290d0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
290e0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
290f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
29100 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
29110 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
29120 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
29130 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
29140 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
29150 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
29160 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
29170 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
29180 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
29190 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
291a0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
291b0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
291c0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
291d0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
291e0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
291f0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
29200 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
29210 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
29220 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
29230 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
29240 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
29250 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
29260 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
29270 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
29280 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
29290 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
292a0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
292b0 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
292c0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
292d0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
292e0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
292f0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
29300 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
29310 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
29320 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
29330 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
29340 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
29350 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
29360 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
29370 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
29380 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
29390 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
293a0 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
293b0 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
293c0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
293d0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
293e0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
293f0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
29400 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
29410 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
29420 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
29430 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
29440 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
29450 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
29460 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
29470 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
29480 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
29490 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
294a0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
294b0 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
294c0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
294d0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
294e0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
294f0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
29500 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
29510 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
29520 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
29530 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
29540 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
29550 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
29560 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
29570 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
29580 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
29590 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
295a0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
295b0 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65  vfs=unix-dotfile
295c0 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
295d0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
295e0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
295f0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
29600 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66  l VFS "unix-dotf
29610 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20  ile".**         
29620 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66   that uses dot-f
29630 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  iles in place of
29640 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20   posix advisory 
29650 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e  locking..** <tr>
29660 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
29670 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
29680 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
29690 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
296a0 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
296b0 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
296c0 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
296d0 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
296e0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
296f0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
29700 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
29710 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
29720 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
29730 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
29740 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
29750 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
29760 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
29770 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
29780 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
29790 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
297a0 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
297b0 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
297c0 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
297d0 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
297e0 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
297f0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
29800 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
29810 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
29820 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
29830 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
29840 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
29850 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
29860 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
29870 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
29880 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
29890 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
298a0 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
298b0 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
298c0 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
298d0 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
298e0 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
298f0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
29900 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
29910 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
29920 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
29930 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
29940 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
29950 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
29960 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
29970 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
29980 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
29990 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
299a0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
299b0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
299c0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
299d0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
299e0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
299f0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
29a00 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
29a10 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
29a20 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
29a30 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
29a40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
29a50 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
29a60 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
29a70 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
29a80 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
29a90 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
29aa0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
29ab0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
29ac0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
29ad0 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
29ae0 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
29af0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
29b00 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
29b10 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
29b20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
29b30 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
29b40 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
29b50 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y].*/.int sqlite
29b60 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
29b70 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
29b80 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
29b90 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
29ba0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
29bb0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
29bc0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
29bd0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
29be0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
29bf0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
29c00 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
29c10 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
29c20 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
29c30 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
29c40 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
29c50 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
29c60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
29c70 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
29c80 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
29c90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
29ca0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
29cb0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
29cc0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
29cd0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
29ce0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
29cf0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
29d00 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
29d10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
29d20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
29d30 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
29d40 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
29d50 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
29d60 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
29d70 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
29d80 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
29d90 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
29da0 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
29db0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
29dc0 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
29dd0 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
29de0 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
29df0 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
29e00 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
29e10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
29e20 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
29e30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
29e40 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
29e50 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
29e60 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
29e70 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
29e80 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
29e90 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
29ea0 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
29eb0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
29ec0 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
29ed0 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
29ee0 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
29ef0 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
29f00 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
29f10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
29f20 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
29f30 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
29f40 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
29f50 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
29f60 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
29f70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
29f80 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
29f90 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
29fa0 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
29fb0 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
29fc0 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
29fd0 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
29fe0 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
29ff0 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
2a000 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
2a010 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
2a020 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
2a030 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
2a040 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
2a050 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
2a060 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
2a070 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
2a080 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
2a090 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
2a0a0 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
2a0b0 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
2a0c0 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
2a0d0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
2a0e0 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
2a0f0 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
2a100 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
2a110 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
2a120 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
2a130 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
2a140 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
2a150 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
2a160 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
2a170 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
2a180 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
2a190 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
2a1a0 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
2a1b0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
2a1c0 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
2a1d0 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
2a1e0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
2a1f0 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
2a200 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
2a210 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
2a220 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
2a230 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
2a240 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
2a250 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
2a260 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
2a270 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
2a280 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
2a290 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
2a2a0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
2a2b0 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
2a2c0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
2a2d0 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
2a2e0 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
2a2f0 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
2a300 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
2a310 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
2a320 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
2a330 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
2a340 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
2a350 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
2a360 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
2a370 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
2a380 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
2a390 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
2a3a0 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
2a3b0 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
2a3c0 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
2a3d0 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
2a3e0 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
2a3f0 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
2a400 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
2a410 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
2a420 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
2a430 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
2a440 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
2a450 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
2a460 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
2a470 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
2a480 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
2a490 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
2a4a0 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
2a4b0 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
2a4c0 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
2a4d0 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
2a4e0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
2a4f0 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
2a500 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
2a510 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
2a520 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
2a530 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2a540 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
2a550 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b  .**.** See the [
2a560 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 64 6f  URI filename] do
2a570 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
2a580 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
2a590 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74  mation..*/.const
2a5a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
2a5b0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
2a5c0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
2a5d0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
2a5e0 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c  zParam);.int sql
2a5f0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
2a600 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
2a610 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
2a620 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
2a630 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69  ault);.sqlite3_i
2a640 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
2a650 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
2a660 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
2a670 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2a680 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
2a690 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
2a6a0 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d  nd Messages.** M
2a6b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
2a6c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2a6d0 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33  t recent sqlite3
2a6e0 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
2a6f0 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20  ciated with .** 
2a700 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2a710 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20  tion] D failed, 
2a720 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2a730 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65  _errcode(D) inte
2a740 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
2a750 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
2a760 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
2a770 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2a780 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a  ode] for that.**
2a790 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 5e 54   API call..** ^T
2a7a0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
2a7b0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
2a7c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
2a7d0 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
2a7e0 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
2a7f0 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
2a800 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2a810 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
2a820 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2a830 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
2a840 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  led..**.** The v
2a850 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2a860 79 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  y sqlite3_errcod
2a870 65 28 29 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  e() and/or.** sq
2a880 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
2a890 72 72 63 6f 64 65 28 29 20 6d 69 67 68 74 20 63  rrcode() might c
2a8a0 68 61 6e 67 65 20 77 69 74 68 20 65 61 63 68 20  hange with each 
2a8b0 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 45 78 63  API call..** Exc
2a8c0 65 70 74 2c 20 74 68 65 72 65 20 61 72 65 20 73  ept, there are s
2a8d0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 74  ome interfaces t
2a8e0 68 61 74 20 61 72 65 20 67 75 61 72 61 6e 74 65  hat are guarante
2a8f0 65 64 20 74 6f 20 6e 65 76 65 72 0a 2a 2a 20 63  ed to never.** c
2a900 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
2a910 6f 66 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  of the error cod
2a920 65 2e 20 20 54 68 65 20 65 72 72 6f 72 2d 63 6f  e.  The error-co
2a930 64 65 20 70 72 65 73 65 72 76 69 6e 67 0a 2a 2a  de preserving.**
2a940 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 3a   interfaces are:
2a950 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2a960 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 63  li> sqlite3_errc
2a970 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71  ode().** <li> sq
2a980 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
2a990 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e  rrcode().** <li>
2a9a0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
2a9b0 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ).** <li> sqlite
2a9c0 33 5f 65 72 72 6d 73 67 31 36 28 29 0a 2a 2a 20  3_errmsg16().** 
2a9d0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  </ul>.**.** ^The
2a9e0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
2a9f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
2aa00 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
2aa10 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
2aa20 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
2aa30 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
2aa40 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
2aa50 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
2aa60 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
2aa70 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
2aa80 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
2aa90 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
2aaa0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
2aab0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2aac0 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
2aad0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
2aae0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
2aaf0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
2ab00 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
2ab10 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
2ab20 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
2ab30 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
2ab40 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
2ab50 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
2ab60 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
2ab70 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
2ab80 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
2ab90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2aba0 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
2abb0 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
2abc0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
2abd0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
2abe0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
2abf0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
2ac00 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
2ac10 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
2ac20 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
2ac30 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
2ac40 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
2ac50 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
2ac60 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
2ac70 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
2ac80 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
2ac90 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
2aca0 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
2acb0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
2acc0 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
2acd0 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
2ace0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
2acf0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
2ad00 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
2ad10 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2ad20 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
2ad30 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
2ad40 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
2ad50 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
2ad60 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
2ad70 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
2ad80 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
2ad90 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
2ada0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
2adb0 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
2adc0 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
2add0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
2ade0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2adf0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
2ae00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
2ae10 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
2ae20 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
2ae30 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
2ae40 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
2ae50 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
2ae60 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
2ae70 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
2ae80 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
2ae90 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
2aea0 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
2aeb0 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
2aec0 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
2aed0 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
2aee0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
2aef0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
2af00 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
2af10 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
2af20 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
2af30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
2af40 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
2af50 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
2af60 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
2af70 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
2af80 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
2af90 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
2afa0 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
2afb0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
2afc0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
2afd0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2afe0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
2aff0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
2b000 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
2b010 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
2b020 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2b030 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
2b040 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b050 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74  F: Prepared Stat
2b060 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
2b070 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
2b080 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
2b090 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b0a0 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
2b0b0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
2b0c0 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
2b0d0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
2b0e0 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20  atement that.** 
2b0f0 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65  has been compile
2b100 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f  d into binary fo
2b110 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20  rm and is ready 
2b120 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e  to be evaluated.
2b130 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20  .**.** Think of 
2b140 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
2b150 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65  nt as a separate
2b160 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61   computer progra
2b170 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69  m.  The.** origi
2b180 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20  nal SQL text is 
2b190 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20  source code.  A 
2b1a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b1b0 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73  nt object .** is
2b1c0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62   the compiled ob
2b1d0 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20  ject code.  All 
2b1e0 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  SQL must be conv
2b1f0 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20  erted into a.** 
2b200 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b210 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e  nt before it can
2b220 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   be run..**.** T
2b230 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66  he life-cycle of
2b240 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2b250 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75  ement object usu
2b260 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74  ally goes like t
2b270 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
2b280 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
2b290 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2b2a0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69  ement object usi
2b2b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2b2c0 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c  are_v2()]..** <l
2b2d0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
2b2e0 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75  o [parameters] u
2b2f0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2b300 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
2b310 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
2b320 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
2b330 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
2b340 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
2b350 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
2b360 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
2b370 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2b380 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2b390 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
2b3a0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
2b3b0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
2b3c0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
2b3d0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
2b3e0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
2b3f0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
2b400 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b410 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79  ..** </ol>.*/.ty
2b420 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2b430 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
2b440 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
2b450 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
2b460 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48  e Limits.** METH
2b470 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
2b480 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
2b490 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
2b4a0 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
2b4b0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
2b4c0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
2b4d0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
2b4e0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
2b4f0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2b500 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
2b510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b520 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
2b530 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
2b540 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
2b550 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2b560 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
2b570 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
2b580 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
2b590 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
2b5a0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
2b5b0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
2b5c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2b5d0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
2b5e0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
2b5f0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
2b600 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
2b610 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
2b620 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
2b630 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
2b640 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
2b650 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
2b660 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
2b670 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
2b680 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
2b690 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
2b6a0 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
2b6b0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
2b6c0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
2b6d0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
2b6e0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
2b6f0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
2b700 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
2b710 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
2b720 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
2b730 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
2b740 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
2b750 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
2b760 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
2b770 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
2b780 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
2b790 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
2b7a0 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
2b7b0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2b7c0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
2b7d0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
2b7e0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
2b7f0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
2b800 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2b810 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
2b820 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
2b830 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
2b840 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
2b850 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
2b860 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
2b870 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
2b880 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
2b890 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
2b8a0 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
2b8b0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
2b8c0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
2b8d0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2b8e0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
2b8f0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
2b900 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
2b910 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
2b920 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
2b930 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
2b940 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
2b950 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
2b960 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
2b970 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
2b980 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
2b990 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
2b9a0 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
2b9b0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
2b9c0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
2b9d0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
2b9e0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
2b9f0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
2ba00 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
2ba10 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
2ba20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
2ba30 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
2ba40 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
2ba50 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
2ba60 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
2ba70 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
2ba80 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
2ba90 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
2baa0 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
2bab0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
2bac0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
2bad0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
2bae0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
2baf0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
2bb00 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
2bb10 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
2bb20 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
2bb30 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
2bb40 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
2bb50 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
2bb60 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
2bb70 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
2bb80 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
2bb90 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
2bba0 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
2bbb0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
2bbc0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
2bbd0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
2bbe0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
2bbf0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
2bc00 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
2bc10 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
2bc20 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
2bc30 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
2bc40 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
2bc50 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
2bc60 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
2bc70 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
2bc80 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
2bc90 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
2bca0 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
2bcb0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
2bcc0 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
2bcd0 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
2bce0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
2bcf0 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
2bd00 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
2bd10 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
2bd20 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
2bd30 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
2bd40 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
2bd50 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
2bd60 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
2bd70 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
2bd80 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
2bd90 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
2bda0 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
2bdb0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
2bdc0 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
2bdd0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2bde0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
2bdf0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2be00 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
2be10 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
2be20 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
2be30 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
2be40 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
2be50 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
2be60 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
2be70 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
2be80 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2be90 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
2bea0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
2beb0 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
2bec0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2bed0 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
2bee0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
2bef0 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
2bf00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2bf10 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2bf20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
2bf30 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
2bf40 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
2bf50 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
2bf60 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2bf70 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2bf80 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
2bf90 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
2bfa0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
2bfb0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2bfc0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
2bfd0 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
2bfe0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
2bff0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
2c000 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2c010 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
2c020 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
2c030 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
2c040 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2c050 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
2c060 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
2c070 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
2c080 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
2c090 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2c0a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
2c0b0 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
2c0c0 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
2c0d0 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
2c0e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2c0f0 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
2c100 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
2c110 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
2c120 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2c130 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
2c140 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
2c150 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
2c160 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
2c170 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
2c180 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71  atement.  If [sq
2c190 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c1a0 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71  ()] or.** the eq
2c1b0 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74  uivalent tries t
2c1c0 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65  o allocate space
2c1d0 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74   for more than t
2c1e0 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73  his many opcodes
2c1f0 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20  .** in a single 
2c200 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c210 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f  nt, an SQLITE_NO
2c220 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74  MEM error is ret
2c230 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
2c240 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2c250 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
2c260 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2c270 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2c280 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
2c290 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2c2a0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
2c2b0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
2c2c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2c2d0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
2c2e0 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
2c2f0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
2c300 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2c310 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2c320 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
2c330 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
2c340 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
2c350 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2c360 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2c370 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
2c380 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2c390 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
2c3a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2c3b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
2c3c0 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
2c3d0 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
2c3e0 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
2c3f0 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
2c400 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2c410 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2c420 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
2c430 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
2c440 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
2c450 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2c460 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
2c470 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
2c480 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
2c490 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
2c4a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2c4b0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
2c4c0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2c4d0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
2c4e0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2c4f0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
2c500 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
2c510 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
2c520 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2c530 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
2c540 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
2c550 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2c560 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
2c570 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2c580 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
2c590 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
2c5a0 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
2c5b0 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
2c5c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
2c5d0 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
2c5e0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
2c5f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
2c600 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
2c610 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
2c620 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2c630 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
2c640 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2c650 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2c660 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
2c670 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
2c680 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2c690 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
2c6a0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
2c6b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2c6c0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2c6d0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
2c6e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2c6f0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
2c700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
2c710 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2c720 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2c730 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
2c740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c750 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
2c760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c770 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
2c780 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
2c790 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
2c7a0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
2c7b0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2c7c0 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
2c7d0 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
2c7e0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2c7f0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
2c800 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
2c810 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
2c820 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
2c830 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
2c840 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 20 46  I3REF: Prepare F
2c850 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
2c860 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
2c870 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73 20  e various flags 
2c880 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 73 73  that can be pass
2c890 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70  ed into.** "prep
2c8a0 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65 72  Flags" parameter
2c8b0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2c8c0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 61  _prepare_v3()] a
2c8d0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
2c8e0 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69  repare16_v3()] i
2c8f0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a  nterfaces..**.**
2c900 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20 62   New flags may b
2c910 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
2c920 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
2c930 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  Lite..**.** <dl>
2c940 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45  .** [[SQLITE_PRE
2c950 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 5d  PARE_PERSISTENT]
2c960 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50  ] ^(<dt>SQLITE_P
2c970 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2c980 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
2c990 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2c9a0 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61 67  _PERSISTENT flag
2c9b0 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74 68   is a hint to th
2c9c0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a  e query planner.
2c9d0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70  ** that the prep
2c9e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77  ared statement w
2c9f0 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64 20  ill be retained 
2ca00 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20  for a long time 
2ca10 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20  and.** probably 
2ca20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d 65  reused many time
2ca30 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74 68  s.)^ ^Without th
2ca40 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65  is flag, [sqlite
2ca50 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 0a  3_prepare_v3()].
2ca60 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2ca70 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
2ca80 61 73 73 75 6d 65 20 74 68 61 74 20 74 68 65 20  assume that the 
2ca90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2caa0 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75  nt will .** be u
2cab0 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72  sed just once or
2cac0 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20 74   at most a few t
2cad0 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64 65  imes and then de
2cae0 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a  stroyed using.**
2caf0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2cb00 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c 79  ze()] relatively
2cb10 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72 65   soon. The curre
2cb20 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
2cb30 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69  n acts.** on thi
2cb40 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64 69  s hint by avoidi
2cb50 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b 6c  ng the use of [l
2cb60 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d  ookaside memory]
2cb70 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a   so as not to.**
2cb80 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69 6d   deplete the lim
2cb90 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f  ited store of lo
2cba0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20  okaside memory. 
2cbb0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
2cbc0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79  of.** SQLite may
2cbd0 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69 6e   act on this hin
2cbe0 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a  t differently..*
2cbf0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52  *.** [[SQLITE_PR
2cc00 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 5d  EPARE_NORMALIZE]
2cc10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45  ] <dt>SQLITE_PRE
2cc20 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 3c 2f  PARE_NORMALIZE</
2cc30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53  dt>.** <dd>The S
2cc40 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2cc50 52 4d 41 4c 49 5a 45 20 66 6c 61 67 20 69 73 20  RMALIZE flag is 
2cc60 61 20 6e 6f 2d 6f 70 2e 20 54 68 69 73 20 66 6c  a no-op. This fl
2cc70 61 67 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 65  ag used.** to be
2cc80 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 61 6e   required for an
2cc90 79 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  y prepared state
2cca0 6d 65 6e 74 20 74 68 61 74 20 77 61 6e 74 65 64  ment that wanted
2ccb0 20 74 6f 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b   to use the.** [
2ccc0 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a  sqlite3_normaliz
2ccd0 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72 66  ed_sql()] interf
2cce0 61 63 65 2e 20 20 48 6f 77 65 76 65 72 2c 20 74  ace.  However, t
2ccf0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  he.** [sqlite3_n
2cd00 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 29 5d  ormalized_sql()]
2cd10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
2cd20 77 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 61  w available to a
2cd30 6c 6c 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  ll.** prepared s
2cd40 74 61 74 65 6d 65 6e 74 73 2c 20 72 65 67 61 72  tatements, regar
2cd50 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2cd60 20 6f 72 20 6e 6f 74 20 74 68 65 79 20 75 73 65   or not they use
2cd70 20 74 68 69 73 0a 2a 2a 20 66 6c 61 67 2e 0a 2a   this.** flag..*
2cd80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52  *.** [[SQLITE_PR
2cd90 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 5d 5d 20  EPARE_NO_VTAB]] 
2cda0 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41  <dt>SQLITE_PREPA
2cdb0 52 45 5f 4e 4f 5f 56 54 41 42 3c 2f 64 74 3e 0a  RE_NO_VTAB</dt>.
2cdc0 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
2cdd0 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41  E_PREPARE_NO_VTA
2cde0 42 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  B flag causes th
2cdf0 65 20 53 51 4c 20 63 6f 6d 70 69 6c 65 72 0a 2a  e SQL compiler.*
2ce00 2a 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 20 65  * to return an e
2ce10 72 72 6f 72 20 28 65 72 72 6f 72 20 63 6f 64 65  rror (error code
2ce20 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 29 20 69   SQLITE_ERROR) i
2ce30 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2ce40 75 73 65 73 0a 2a 2a 20 61 6e 79 20 76 69 72 74  uses.** any virt
2ce50 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 20 3c  ual tables..** <
2ce60 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
2ce70 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2ce80 45 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20  ERSISTENT       
2ce90 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66         0x01.#def
2cea0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ine SQLITE_PREPA
2ceb0 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 20 20 20 20  RE_NORMALIZE    
2cec0 20 20 20 20 20 20 20 20 20 20 20 30 78 30 32 0a             0x02.
2ced0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
2cee0 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 20 20  REPARE_NO_VTAB  
2cef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
2cf00 78 30 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x04../*.** CAPI3
2cf10 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
2cf20 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2cf30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2cf40 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2cf50 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  iler}.** METHOD:
2cf60 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53   sqlite3.** CONS
2cf70 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
2cf80 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  _stmt.**.** To e
2cf90 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74  xecute an SQL st
2cfa0 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74  atement, it must
2cfb0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
2cfc0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
2cfd0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
2cfe0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
2cff0 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c  e routines.  Or,
2d000 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
2d010 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2d020 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74  ** are construct
2d030 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65  ors for the [pre
2d040 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d050 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54   object..**.** T
2d060 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f 75  he preferred rou
2d070 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b  tine to use is [
2d080 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d090 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b  v2()].  The.** [
2d0a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2d0b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
2d0c0 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c  legacy and shoul
2d0d0 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a  d be avoided..**
2d0e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d0f0 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65  e_v3()] has an e
2d100 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73 22  xtra "prepFlags"
2d110 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20   option that is 
2d120 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63  used.** for spec
2d130 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  ial purposes..**
2d140 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74  .** The use of t
2d150 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61  he UTF-8 interfa
2d160 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65 64  ces is preferred
2d170 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72 72  , as SQLite curr
2d180 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c  ently.** does al
2d190 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20  l parsing using 
2d1a0 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d  UTF-8.  The UTF-
2d1b0 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  16 interfaces ar
2d1c0 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73  e provided.** as
2d1d0 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20   a convenience. 
2d1e0 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65   The UTF-16 inte
2d1f0 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63  rfaces work by c
2d200 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a  onverting the.**
2d210 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f   input text into
2d220 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76   UTF-8, then inv
2d230 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73  oking the corres
2d240 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e  ponding UTF-8 in
2d250 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
2d260 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2d270 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
2d280 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d290 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
2d2a0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
2d2b0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2d2c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2d2d0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
2d2e0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
2d2f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
2d300 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
2d310 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
2d320 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
2d330 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
2d340 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
2d350 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
2d360 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2d370 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
2d380 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
2d390 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
2d3a0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2d3b0 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  re(), sqlite3_pr
2d3c0 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61  epare_v2(),.** a
2d3d0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2d3e0 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v3().** inter
2d3f0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
2d400 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2d410 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65  pare16(), sqlite
2d420 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2d430 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2d440 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20  _prepare16_v3() 
2d450 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
2d460 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
2d470 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61  argument is nega
2d480 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20  tive, then zSql 
2d490 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
2d4a0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
2d4b0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
2d4c0 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76  nByte is positiv
2d4d0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
2d4e0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2d4f0 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
2d500 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20  Sql.  ^If nByte 
2d510 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f  is zero, then no
2d520 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d530 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61  tement is genera
2d540 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ted..** If the c
2d550 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74  aller knows that
2d560 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
2d570 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
2d580 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  inated, then.** 
2d590 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
2d5a0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
2d5b0 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e  antage to passin
2d5c0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
2d5d0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
2d5e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d5f0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
2d600 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
2d610 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
2d620 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  nul-terminator..
2d630 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
2d640 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
2d650 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
2d660 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
2d670 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
2d680 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
2d690 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
2d6a0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
2d6b0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2d6c0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
2d6d0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
2d6e0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
2d6f0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
2d700 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
2d710 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
2d720 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
2d730 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
2d740 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
2d750 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
2d760 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2d770 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
2d780 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
2d790 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
2d7a0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
2d7b0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
2d7c0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
2d7d0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
2d7e0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
2d7f0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
2d800 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
2d810 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
2d820 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
2d830 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
2d840 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
2d850 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
2d860 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
2d870 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
2d880 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
2d890 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
2d8a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2d8b0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
2d8c0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
2d8d0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
2d8e0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2d8f0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
2d900 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d910 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
2d920 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2d930 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
2d940 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
2d950 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2d960 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2d970 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d980 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2d990 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65  are_v3(), sqlite
2d9a0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2d9b0 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2d9c0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20  _prepare16_v3() 
2d9d0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
2d9e0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
2d9f0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
2da00 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e  .** The older in
2da10 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74 65  terfaces (sqlite
2da20 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
2da30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2da40 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61  6()).** are reta
2da50 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
2da60 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
2da70 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
2da80 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
2da90 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20  ** ^In the "vX" 
2daa0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
2dab0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dac0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
2dad0 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
2dae0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2daf0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
2db00 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
2db10 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
2db20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
2db30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2db40 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
2db50 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
2db60 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
2db70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
2db80 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2db90 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2dba0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
2dbb0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
2dbc0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
2dbd0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
2dbe0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
2dbf0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
2dc00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2dc10 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
2dc20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
2dc30 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
2dc40 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
2dc50 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
2dc60 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
2dc70 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
2dc80 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
2dc90 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
2dca0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
2dcb0 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
2dcc0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
2dcd0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
2dce0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
2dcf0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
2dd00 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
2dd10 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
2dd20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
2dd30 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
2dd40 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
2dd50 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
2dd60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2dd70 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
2dd80 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
2dd90 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2dda0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
2ddb0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
2ddc0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
2ddd0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
2dde0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2ddf0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
2de00 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
2de10 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
2de20 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
2de30 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
2de40 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
2de50 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
2de60 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
2de70 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
2de80 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
2de90 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
2dea0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2deb0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2dec0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
2ded0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
2dee0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
2def0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
2df00 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2df10 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
2df20 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
2df30 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
2df40 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
2df50 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
2df60 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
2df70 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
2df80 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
2df90 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
2dfa0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
2dfb0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2dfc0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
2dfd0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
2dfe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2dff0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
2e000 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
2e010 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
2e020 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
2e030 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
2e040 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
2e050 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
2e060 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2e070 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
2e080 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
2e090 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
2e0a0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
2e0b0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
2e0c0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2e0d0 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
2e0e0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
2e0f0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
2e100 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
2e110 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
2e120 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
2e130 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  d..** </li>.** <
2e140 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73  /ol>.**.** <p>^s
2e150 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e160 33 28 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d  3() differs from
2e170 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2e180 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61  _v2() only in ha
2e190 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72  ving.** the extr
2e1a0 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61  a prepFlags para
2e1b0 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 73 20  meter, which is 
2e1c0 61 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73  a bit array cons
2e1d0 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f  isting of zero o
2e1e0 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65  r.** more of the
2e1f0 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45   [SQLITE_PREPARE
2e200 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49  _PERSISTENT|SQLI
2e210 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c  TE_PREPARE_*] fl
2e220 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ags.  ^The.** sq
2e230 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e240 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
2e250 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  ks exactly the s
2e260 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65  ame as.** sqlite
2e270 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 77  3_prepare_v3() w
2e280 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46  ith a zero prepF
2e290 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a  lags parameter..
2e2a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
2e2b0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
2e2c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2e2d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2e2e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2e2f0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2e300 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2e310 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2e320 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2e330 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2e340 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2e350 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2e360 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2e370 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2e380 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2e390 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2e3a0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2e3b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2e3c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2e3d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2e3e0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2e3f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
2e400 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2e410 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2e420 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2e430 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2e440 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2e450 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2e460 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2e470 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2e480 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2e490 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2e4a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2e4b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2e4c0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2e4d0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2e4e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2e4f0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2e500 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2e510 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2e520 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2e530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2e540 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v3(.  sqlite3 *d
2e550 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2e560 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2e570 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2e580 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2e590 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2e5a0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2e5b0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2e5c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2e5d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2e5e0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2e5f0 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  /.  unsigned int
2e600 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a   prepFlags, /* Z
2e610 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49  ero or more SQLI
2e620 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67  TE_PREPARE_ flag
2e630 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  s */.  sqlite3_s
2e640 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2e650 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2e660 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2e670 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2e680 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2e690 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2e6a0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2e6b0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2e6c0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
2e6d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2e6e0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2e6f0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2e700 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2e710 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2e720 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2e730 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2e740 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2e750 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2e760 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2e770 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2e780 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2e790 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2e7a0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2e7b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2e7c0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2e7d0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2e7e0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2e7f0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2e800 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e810 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2e820 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2e830 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2e840 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2e850 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2e860 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2e870 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2e880 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2e890 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e8a0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2e8b0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2e8c0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2e8d0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2e8e0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2e8f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2e900 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2e910 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2e920 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2e930 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2e940 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2e950 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20  prepare16_v3(.  
2e960 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2e970 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2e980 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2e990 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2e9a0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2e9b0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2e9c0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2e9d0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2e9e0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2e9f0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2ea00 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75  in bytes. */.  u
2ea10 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70  nsigned int prep
2ea20 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f  Flags, /* Zero o
2ea30 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52  r more SQLITE_PR
2ea40 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a  EPARE_ flags */.
2ea50 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2ea60 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2ea70 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2ea80 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2ea90 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2eaa0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2eab0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2eac0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2ead0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2eae0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
2eaf0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54  ement SQL.** MET
2eb00 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2eb10 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2eb20 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65  ite3_sql(P) inte
2eb30 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2eb40 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70  pointer to a cop
2eb50 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a  y of the UTF-8.*
2eb60 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
2eb70 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61  to create [prepa
2eb80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2eb90 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65   if P was.** cre
2eba0 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
2ebb0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2ebc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ebd0 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v3()],.** [sqli
2ebe0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2ebf0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
2ec00 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2ec10 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2ec20 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
2ec30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2ec40 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2ec50 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69   a UTF-8.** stri
2ec60 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
2ec70 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72  e SQL text of pr
2ec80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ec90 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e   P with.** [boun
2eca0 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78  d parameters] ex
2ecb0 70 61 6e 64 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  panded..** ^The 
2ecc0 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a  sqlite3_normaliz
2ecd0 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2ece0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2ecf0 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2ed00 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2ed10 69 6e 69 6e 67 20 74 68 65 20 6e 6f 72 6d 61 6c  ining the normal
2ed20 69 7a 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66  ized SQL text of
2ed30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ed40 65 6e 74 20 50 2e 20 20 54 68 65 0a 2a 2a 20 73  ent P.  The.** s
2ed50 65 6d 61 6e 74 69 63 73 20 75 73 65 64 20 74 6f  emantics used to
2ed60 20 6e 6f 72 6d 61 6c 69 7a 65 20 61 20 53 51 4c   normalize a SQL
2ed70 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 75   statement are u
2ed80 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 73  nspecified and s
2ed90 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61  ubject.** to cha
2eda0 6e 67 65 2e 20 20 41 74 20 61 20 6d 69 6e 69 6d  nge.  At a minim
2edb0 75 6d 2c 20 6c 69 74 65 72 61 6c 20 76 61 6c 75  um, literal valu
2edc0 65 73 20 77 69 6c 6c 20 62 65 20 72 65 70 6c 61  es will be repla
2edd0 63 65 64 20 77 69 74 68 20 73 75 69 74 61 62 6c  ced with suitabl
2ede0 65 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  e.** placeholder
2edf0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  s..**.** ^(For e
2ee00 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65  xample, if a pre
2ee10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ee20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
2ee30 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74   the SQL.** text
2ee40 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2ee50 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d  yz" and if param
2ee60 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75  eter $abc is bou
2ee70 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33  nd to integer 23
2ee80 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65  45.** and parame
2ee90 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f  ter :xyz is unbo
2eea0 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  und, then sqlite
2eeb0 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74  3_sql() will ret
2eec0 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  urn.** the origi
2eed0 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c  nal string, "SEL
2eee0 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62  ECT $abc,:xyz" b
2eef0 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  ut sqlite3_expan
2ef00 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c  ded_sql().** wil
2ef10 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54  l return "SELECT
2ef20 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a   2345,NULL".)^.*
2ef30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ef40 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2ef50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ef60 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  ns NULL if insuf
2ef70 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a  ficient memory.*
2ef80 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74  * is available t
2ef90 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
2efa0 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73  t, or if the res
2efb0 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64  ult would exceed
2efc0 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69   the.** the maxi
2efd0 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74  mum string lengt
2efe0 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  h determined by 
2eff0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  the [SQLITE_LIMI
2f000 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a  T_LENGTH]..**.**
2f010 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52   ^The [SQLITE_TR
2f020 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
2f030 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2f040 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73  ion limits the s
2f050 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20  ize of.** bound 
2f060 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73  parameter expans
2f070 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c  ions.  ^The [SQL
2f080 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20  ITE_OMIT_TRACE] 
2f090 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
2f0a0 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71  option causes sq
2f0b0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2f0c0 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72  ql() to always r
2f0d0 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  eturn NULL..**.*
2f0e0 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 73 20 72  * ^The strings r
2f0f0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2f100 65 33 5f 73 71 6c 28 50 29 20 61 6e 64 20 73 71  e3_sql(P) and sq
2f110 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64  lite3_normalized
2f120 5f 73 71 6c 28 50 29 0a 2a 2a 20 61 72 65 20 6d  _sql(P).** are m
2f130 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65  anaged by SQLite
2f140 20 61 6e 64 20 61 72 65 20 61 75 74 6f 6d 61 74   and are automat
2f150 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65  ically freed whe
2f160 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  n the prepared.*
2f170 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  * statement is f
2f180 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68  inalized..** ^Th
2f190 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2f1a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70  d by sqlite3_exp
2f1b0 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e  anded_sql(P), on
2f1c0 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2f1d0 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20  .** is obtained 
2f1e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2f1f0 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74  lloc()] and must
2f200 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20   be free by the 
2f210 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62  application.** b
2f220 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  y passing it to 
2f230 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2f240 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2f250 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
2f260 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2f270 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
2f280 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71  _expanded_sql(sq
2f290 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2f2a0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2f2b0 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a  sqlite3_normaliz
2f2c0 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2f2d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2f2e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2f2f0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
2f300 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
2f310 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
2f320 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f330 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2f340 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2f350 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
2f360 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2f370 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2f380 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
2f390 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2f3a0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
2f3b0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
2f3c0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
2f3d0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2f3e0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
2f3f0 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
2f400 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f410 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
2f420 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
2f430 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
2f440 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2f450 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
2f460 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
2f470 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2f480 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
2f490 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
2f4a0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
2f4b0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
2f4c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
2f4d0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
2f4e0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
2f4f0 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
2f500 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2f510 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
2f520 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
2f530 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2f540 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
2f550 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
2f560 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
2f570 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
2f580 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
2f590 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
2f5a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
2f5b0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2f5c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
2f5d0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
2f5e0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2f5f0 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
2f600 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
2f610 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
2f620 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
2f630 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
2f640 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
2f650 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
2f660 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
2f670 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
2f680 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2f690 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2f6a0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
2f6b0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
2f6c0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
2f6d0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
2f6e0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2f6f0 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
2f700 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
2f710 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
2f720 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
2f730 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
2f740 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
2f750 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
2f760 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
2f770 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
2f780 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2f790 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2f7a0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
2f7b0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
2f7c0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
2f7d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
2f7e0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
2f7f0 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
2f800 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
2f810 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
2f820 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2f830 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
2f840 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  k..** ^The sqlit
2f850 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2f860 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2f870 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42  urns true for [B
2f880 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b  EGIN] since.** [
2f890 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65  BEGIN] merely se
2f8a0 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67  ts internal flag
2f8b0 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49  s, but the [BEGI
2f8c0 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54  N|BEGIN IMMEDIAT
2f8d0 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e  E] and.** [BEGIN
2f8e0 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45  |BEGIN EXCLUSIVE
2f8f0 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f  ] commands do to
2f900 75 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  uch the database
2f910 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74   and so.** sqlit
2f920 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2f930 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  () returns false
2f940 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61   for those comma
2f950 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
2f960 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2f970 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
2f980 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2f990 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 54  API3REF: Query T
2f9a0 68 65 20 45 58 50 4c 41 49 4e 20 53 65 74 74 69  he EXPLAIN Setti
2f9b0 6e 67 20 46 6f 72 20 41 20 50 72 65 70 61 72 65  ng For A Prepare
2f9c0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  d Statement.** M
2f9d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f9e0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2f9f0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 69 73 65 78  qlite3_stmt_isex
2fa00 70 6c 61 69 6e 28 53 29 20 69 6e 74 65 72 66 61  plain(S) interfa
2fa10 63 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 20  ce returns 1 if 
2fa20 74 68 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  the.** prepared 
2fa30 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 61  statement S is a
2fa40 6e 20 45 58 50 4c 41 49 4e 20 73 74 61 74 65 6d  n EXPLAIN statem
2fa50 65 6e 74 2c 20 6f 72 20 32 20 69 66 20 74 68 65  ent, or 2 if the
2fa60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 53 20  .** statement S 
2fa70 69 73 20 61 6e 20 45 58 50 4c 41 49 4e 20 51 55  is an EXPLAIN QU
2fa80 45 52 59 20 50 4c 41 4e 2e 0a 2a 2a 20 5e 54 68  ERY PLAN..** ^Th
2fa90 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 69  e sqlite3_stmt_i
2faa0 73 65 78 70 6c 61 69 6e 28 53 29 20 69 6e 74 65  sexplain(S) inte
2fab0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 30 20  rface returns 0 
2fac0 69 66 20 53 20 69 73 0a 2a 2a 20 61 6e 20 6f 72  if S is.** an or
2fad0 64 69 6e 61 72 79 20 73 74 61 74 65 6d 65 6e 74  dinary statement
2fae0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
2faf0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
2fb00 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69  e3_stmt_isexplai
2fb10 6e 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  n(sqlite3_stmt *
2fb20 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2fb30 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2fb40 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
2fb50 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
2fb60 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54  een Reset.** MET
2fb70 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2fb80 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2fb90 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2fba0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2fbb0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2fbc0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
2fbd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fbe0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
2fbf0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
2fc00 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
2fc10 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2fc20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20  but has neither 
2fc30 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
2fc40 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  n (returned.** [
2fc50 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f  SQLITE_DONE] fro
2fc60 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  m [sqlite3_step(
2fc70 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e  S)]) nor.** been
2fc80 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
2fc90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
2fca0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
2fcb0 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
2fcc0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2fcd0 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
2fce0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
2fcf0 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
2fd00 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
2fd10 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
2fd20 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
2fd30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fd40 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
2fd50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2fd60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2fd70 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
2fd80 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
2fd90 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2fda0 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
2fdb0 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
2fdc0 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
2fdd0 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
2fde0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fdf0 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
2fe00 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
2fe10 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
2fe20 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
2fe30 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
2fe40 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
2fe50 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
2fe60 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
2fe70 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
2fe80 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
2fe90 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
2fea0 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
2feb0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
2fec0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
2fed0 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
2fee0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2fef0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
2ff00 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
2ff10 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
2ff20 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
2ff30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2ff40 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
2ff50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
2ff60 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
2ff70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
2ff80 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
2ff90 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
2ffa0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
2ffb0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
2ffc0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
2ffd0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2ffe0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
2fff0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
30000 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
30010 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
30020 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
30030 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
30040 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
30050 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
30060 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
30070 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
30080 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
30090 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
300a0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
300b0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
300c0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
300d0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
300e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
300f0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
30100 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
30110 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
30120 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
30130 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30140 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
30150 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
30160 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
30170 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
30180 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
30190 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
301a0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
301b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
301c0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
301d0 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20  e3_value_dup()] 
301e0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
301f0 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75   used to constru
30200 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f  ct a new .** pro
30210 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30220 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70  alue from an unp
30230 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30240 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
30250 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
30260 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
30270 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
30280 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
30290 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
302a0 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
302b0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
302c0 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
302d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
302e0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
302f0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
30300 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
30310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
30320 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
30330 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
30340 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
30350 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
30360 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
30370 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
30380 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
30390 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
303a0 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
303b0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
303c0 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
303d0 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
303e0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
303f0 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
30400 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
30410 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
30420 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
30430 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
30440 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
30450 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
30460 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
30470 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
30480 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
30490 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
304a0 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
304b0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
304c0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
304d0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
304e0 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
304f0 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
30500 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
30510 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
30520 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
30530 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
30540 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
30550 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
30560 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30570 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
30580 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
30590 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
305a0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
305b0 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
305c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
305d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
305e0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
305f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
30600 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
30610 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
30620 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
30630 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
30640 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
30650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30660 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
30670 62 65 20 75 73 65 64 20 61 73 20 61 72 67 75 6d  be used as argum
30680 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ents.** to [sqli
30690 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
306a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69  ()], [sqlite3_bi
306b0 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64  nd_value()], and
306c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
306d0 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68  ue_dup()]..** Th
306e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
306f0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
30700 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
30710 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
30720 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
30730 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30740 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
30750 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
30760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73   sqlite3_value s
30770 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
30780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
30790 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
307a0 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
307b0 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
307c0 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
307d0 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
307e0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
307f0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
30800 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
30810 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
30820 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
30830 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
30840 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
30850 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
30860 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
30870 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
30880 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30890 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
308a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
308b0 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
308c0 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
308d0 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
308e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
308f0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
30900 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
30910 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30920 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
30930 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
30940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
30950 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
30960 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
30970 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
30980 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
30990 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
309a0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
309b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
309c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
309d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
309e0 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
309f0 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
30a00 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
30a10 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
30a20 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
30a30 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
30a40 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
30a50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
30a60 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
30a70 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
30a80 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
30a90 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30aa0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30ab0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
30ac0 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
30ad0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
30ae0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
30af0 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
30b00 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
30b10 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
30b20 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
30b30 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
30b40 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
30b50 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
30b60 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
30b70 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
30b80 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
30b90 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
30ba0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
30bb0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
30bc0 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
30bd0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
30be0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
30bf0 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
30c00 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
30c10 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
30c20 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
30c30 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
30c40 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
30c50 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
30c60 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
30c70 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
30c80 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
30c90 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
30ca0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
30cb0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
30cc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
30cd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
30ce0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
30cf0 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
30d00 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
30d10 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
30d20 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
30d30 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
30d40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
30d50 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
30d60 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
30d70 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
30d80 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
30d90 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
30da0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
30db0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
30dc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
30dd0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
30de0 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
30df0 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
30e00 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
30e10 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
30e20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
30e30 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
30e40 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
30e50 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
30e60 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
30e70 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
30e80 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
30e90 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
30ea0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
30eb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30ec0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
30ed0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
30ee0 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
30ef0 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
30f00 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
30f10 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
30f20 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
30f30 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
30f40 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
30f50 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
30f60 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
30f70 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
30f80 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
30f90 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
30fa0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
30fb0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
30fc0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
30fd0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
30fe0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
30ff0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
31000 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
31010 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
31020 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20  _text16().** or 
31030 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
31040 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  b() is a NULL po
31050 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66  inter then the f
31060 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a  ourth parameter.
31070 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e  ** is ignored an
31080 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74  d the end result
31090 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
310a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
310b0 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  l()..**.** ^(In 
310c0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
310d0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
310e0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
310f0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
31100 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
31110 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
31120 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
31130 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
31140 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
31150 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
31160 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
31170 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
31180 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
31190 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
311a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
311b0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
311c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
311d0 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
311e0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
311f0 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
31200 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
31210 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
31220 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
31230 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
31240 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
31250 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
31260 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
31270 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
31280 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
31290 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
312a0 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
312b0 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
312c0 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
312d0 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
312e0 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
312f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
31300 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  16() or sqlite3_
31310 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68  bind_text64() th
31320 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d  en.** that param
31330 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
31340 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
31350 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
31360 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
31370 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
31380 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
31390 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
313a0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
313b0 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
313c0 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
313d0 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
313e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
313f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
31400 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
31410 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
31420 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
31430 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
31440 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
31450 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
31460 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
31470 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
31480 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
31490 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
314a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42  rgument to the B
314b0 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62  LOB and string b
314c0 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65  inding interface
314d0 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75  s.** is a destru
314e0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
314f0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
31500 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
31510 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
31520 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
31530 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
31540 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
31550 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
31560 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
31570 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
31580 20 74 6f 20 74 68 65 20 62 69 6e 64 20 41 50 49   to the bind API
31590 20 66 61 69 6c 73 2c 0a 2a 2a 20 65 78 63 65 70   fails,.** excep
315a0 74 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  t the destructor
315b0 20 69 73 20 6e 6f 74 20 63 61 6c 6c 65 64 20 69   is not called i
315c0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
315d0 6d 65 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 0a  meter is a NULL.
315e0 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 74 68  ** pointer or th
315f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
31600 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a  er is negative..
31610 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
31620 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
31630 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
31640 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
31650 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
31660 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
31670 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
31680 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
31690 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
316a0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
316b0 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
316c0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
316d0 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
316e0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
316f0 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
31700 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
31710 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
31720 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
31730 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
31740 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
31750 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
31760 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
31770 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75   ^The sixth argu
31780 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
31790 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75  bind_text64() mu
317a0 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  st be one of.** 
317b0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
317c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b  SQLITE_UTF16], [
317d0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
317e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
317f0 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69  6LE].** to speci
31800 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  fy the encoding 
31810 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74  of the text in t
31820 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
31830 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73  er.  If.** the s
31840 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
31850 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
31860 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e  xt64() is not on
31870 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f  e of the.** allo
31880 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e  wed values shown
31890 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68   above, or if th
318a0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
318b0 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20  is different.** 
318c0 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e  from the encodin
318d0 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  g specified by t
318e0 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  he sixth paramet
318f0 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  er, then the beh
31900 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
31910 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
31920 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
31930 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
31940 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
31950 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
31960 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
31970 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
31980 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
31990 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
319a0 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
319b0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
319c0 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
319d0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
319e0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
319f0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
31a00 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
31a10 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
31a20 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
31a30 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
31a40 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
31a50 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
31a60 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
31a70 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
31a80 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
31a90 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
31aa0 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
31ab0 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
31ac0 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
31ad0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
31ae0 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c  d_pointer(S,I,P,
31af0 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75  T,D) routine cau
31b00 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 61 72  ses the I-th par
31b10 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72  ameter in.** [pr
31b20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31b30 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53  ] S to have an S
31b40 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c  QL value of NULL
31b50 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65  , but to also be
31b60 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
31b70 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ith the pointer 
31b80 50 20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44  P of type T.  ^D
31b90 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
31ba0 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20  L pointer or.** 
31bb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64  a pointer to a d
31bc0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
31bd0 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74  on for P. ^SQLit
31be0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
31bf0 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20  e.** destructor 
31c00 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20  D with a single 
31c10 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68  argument of P wh
31c20 65 6e 20 69 74 20 69 73 20 66 69 6e 69 73 68 65  en it is finishe
31c30 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54  d using.** P.  T
31c40 68 65 20 54 20 70 61 72 61 6d 65 74 65 72 20 73  he T parameter s
31c50 68 6f 75 6c 64 20 62 65 20 61 20 73 74 61 74 69  hould be a stati
31c60 63 20 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72  c string, prefer
31c70 61 62 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a  ably a string.**
31c80 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71   literal. The sq
31c90 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74  lite3_bind_point
31ca0 65 72 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  er() routine is 
31cb0 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
31cc0 70 6f 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20  pointer passing 
31cd0 69 6e 74 65 72 66 61 63 65 5d 20 61 64 64 65 64  interface] added
31ce0 20 66 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30   for SQLite 3.20
31cf0 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  .0..**.** ^If an
31d00 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
31d10 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
31d20 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
31d30 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
31d40 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
31d50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31d60 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
31d70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
31d80 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
31d90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
31da0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
31db0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
31dc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31dd0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
31de0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
31df0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
31e00 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
31e10 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
31e20 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
31e30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31e40 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
31e50 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
31e60 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
31e70 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
31e80 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
31e90 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
31ea0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
31eb0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
31ec0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
31ed0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
31ee0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
31ef0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
31f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31f10 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
31f20 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
31f30 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
31f40 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
31f50 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
31f60 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
31f70 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
31f80 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
31f90 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
31fa0 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
31fb0 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
31fc0 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
31fd0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
31fe0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
31ff0 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
32000 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
32010 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
32020 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
32030 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
32040 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
32050 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
32060 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
32070 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
32080 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
32090 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
320a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
320b0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
320c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
320d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
320e0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
320f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
32100 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
32110 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
32120 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
32130 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
32140 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
32150 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
32160 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
32170 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
32180 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
32190 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
321a0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
321b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
321c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
321d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
321e0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
321f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
32200 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
32210 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
32220 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
32230 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
32240 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
32250 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
32260 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
32270 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
32280 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
32290 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
322a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
322b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
322c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
322d0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
322e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
322f0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
32300 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
32310 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
32320 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
32330 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
32340 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
32350 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
32360 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
32370 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
32380 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32390 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
323a0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
323b0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20   encoding);.int 
323c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
323d0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
323e0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
323f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
32400 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
32410 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73  ointer(sqlite3_s
32420 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a  tmt*, int, void*
32430 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f  , const char*,vo
32440 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
32450 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
32460 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
32470 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
32480 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33   n);.int sqlite3
32490 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34  _bind_zeroblob64
324a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
324b0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  int, sqlite3_uin
324c0 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
324d0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
324e0 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
324f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
32500 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
32510 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
32520 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
32530 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
32540 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
32550 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
32560 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
32570 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
32580 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
32590 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
325a0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
325b0 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
325c0 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
325d0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
325e0 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
325f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
32600 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
32610 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
32620 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
32630 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
32640 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
32650 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
32660 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
32670 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
32680 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
32690 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
326a0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
326b0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
326c0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
326d0 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
326e0 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
326f0 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
32700 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
32710 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
32720 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
32730 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
32740 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
32750 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
32760 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
32770 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
32780 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
32790 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
327a0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
327b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
327c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
327d0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
327e0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
327f0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
32800 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
32810 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32820 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
32830 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
32840 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
32850 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
32860 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
32870 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
32880 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
32890 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
328a0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
328b0 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
328c0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
328d0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
328e0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
328f0 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
32900 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
32910 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
32920 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
32930 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
32940 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
32950 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
32960 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
32970 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
32980 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
32990 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
329a0 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
329b0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
329c0 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
329d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
329e0 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
329f0 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
32a00 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
32a10 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
32a20 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
32a30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
32a40 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
32a50 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
32a60 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
32a70 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
32a80 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
32a90 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
32aa0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
32ab0 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
32ac0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
32ad0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
32ae0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
32af0 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
32b00 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
32b10 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
32b20 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
32b30 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
32b40 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
32b50 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
32b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
32b70 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72  pare16_v2()], or
32b80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32b90 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v3()]..**.**
32ba0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
32bb0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
32bc0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
32bd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
32be0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
32bf0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
32c00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
32c10 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
32c20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
32c30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
32c40 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
32c50 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
32c60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
32c70 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
32c80 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
32c90 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
32ca0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
32cb0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
32cc0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
32cd0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
32ce0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
32cf0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
32d00 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
32d10 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
32d20 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
32d30 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
32d40 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
32d50 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
32d60 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
32d70 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
32d80 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
32d90 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
32da0 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
32db0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
32dc0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
32dd0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
32de0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
32df0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
32e00 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
32e10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
32e20 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
32e30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
32e40 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  3()]..**.** See 
32e50 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
32e60 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
32e70 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
32e80 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
32e90 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
32ea0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
32eb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
32ec0 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  me()]..*/.int sq
32ed0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
32ee0 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
32ef0 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
32f00 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
32f10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
32f20 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
32f30 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
32f40 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
32f50 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
32f60 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
32f70 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
32f80 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
32f90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
32fa0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
32fb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
32fc0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
32fd0 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
32fe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
32ff0 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
33000 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
33010 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
33020 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
33030 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
33040 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
33050 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
33060 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
33070 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
33080 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54  esult Set.** MET
33090 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
330a0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
330b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
330c0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
330d0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
330e0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
330f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
33100 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
33110 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61  e returns 0, tha
33120 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20  t means the .** 
33130 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33140 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20  ent] returns no 
33150 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
33160 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
33170 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73  ** ^However, jus
33180 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72  t because this r
33190 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
331a0 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72   positive number
331b0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61   does not.** mea
331c0 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f  n that one or mo
331d0 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20  re rows of data 
331e0 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
331f0 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61  .  ^A SELECT sta
33200 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61  tement.** will a
33210 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73  lways have a pos
33220 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f  itive sqlite3_co
33230 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74  lumn_count() but
33240 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
33250 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73  e.** WHERE claus
33260 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
33270 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74  d the table cont
33280 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65  ent, it might re
33290 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a  turn no rows..**
332a0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
332b0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
332c0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
332d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
332e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
332f0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
33300 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
33310 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
33320 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
33330 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
33340 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
33350 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
33360 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
33370 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
33380 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
33390 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
333a0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
333b0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
333c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
333d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
333e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
333f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
33400 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
33410 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
33420 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
33430 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
33440 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
33450 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
33460 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
33470 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
33480 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
33490 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
334a0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
334b0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
334c0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
334d0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
334e0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
334f0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
33500 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
33510 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
33520 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
33530 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
33540 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
33550 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
33560 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
33570 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
33580 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
33590 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
335a0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
335b0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
335c0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
335d0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
335e0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
335f0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
33600 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
33610 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
33620 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
33630 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
33640 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
33650 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
33660 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
33670 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
33680 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
33690 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
336a0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
336b0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
336c0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
336d0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
336e0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
336f0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
33700 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
33710 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
33720 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
33730 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
33740 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
33750 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
33760 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
33770 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
33780 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
33790 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
337a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
337b0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
337c0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
337d0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
337e0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
337f0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
33800 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
33810 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
33820 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
33830 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
33840 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
33850 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
33860 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
33870 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33880 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
33890 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
338a0 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
338b0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
338c0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
338d0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
338e0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
338f0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
33900 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
33910 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
33920 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
33930 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
33940 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
33950 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
33960 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
33970 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
33980 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
33990 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
339a0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
339b0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
339c0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
339d0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
339e0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
339f0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
33a00 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
33a10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
33a20 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
33a30 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
33a40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
33a50 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
33a60 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
33a70 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
33a80 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
33a90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33aa0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
33ab0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
33ac0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
33ad0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
33ae0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
33af0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
33b00 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
33b10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
33b20 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
33b30 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
33b40 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
33b50 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
33b60 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
33b70 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
33b80 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
33b90 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
33ba0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
33bb0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
33bc0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
33bd0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
33be0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
33bf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
33c00 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
33c10 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
33c20 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
33c30 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
33c40 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
33c50 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
33c60 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
33c70 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
33c80 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
33c90 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
33ca0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
33cb0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
33cc0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
33cd0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
33ce0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
33cf0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
33d00 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
33d10 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
33d20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
33d30 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
33d40 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
33d50 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
33d60 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
33d70 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
33d80 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
33d90 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
33da0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
33db0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
33dc0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
33dd0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
33de0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
33df0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
33e00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
33e10 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
33e20 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
33e30 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
33e40 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
33e50 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
33e60 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
33e70 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
33e80 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
33e90 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
33ea0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
33eb0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
33ec0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
33ed0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
33ee0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
33ef0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
33f00 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
33f10 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
33f20 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
33f30 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
33f40 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
33f50 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
33f60 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
33f70 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
33f80 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
33f90 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
33fa0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
33fb0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
33fc0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
33fd0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
33fe0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
33ff0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
34000 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
34010 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
34020 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
34030 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
34040 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
34050 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
34060 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
34070 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
34080 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
34090 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
340a0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
340b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
340c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
340d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
340e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
340f0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
34100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
34110 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
34120 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
34130 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
34140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
34150 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
34160 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
34170 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
34180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
34190 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
341a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
341b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
341c0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
341d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
341e0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
341f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
34200 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
34210 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
34220 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
34230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
34240 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
34250 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
34260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
34270 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
34280 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
34290 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
342a0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
342b0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
342c0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
342d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
342e0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
342f0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
34300 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
34310 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
34320 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
34330 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
34340 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
34350 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
34360 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
34370 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
34380 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
34390 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
343a0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
343b0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
343c0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
343d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
343e0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
343f0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
34400 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
34410 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
34420 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
34430 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
34440 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
34450 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
34460 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
34470 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
34480 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
34490 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
344a0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
344b0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
344c0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
344d0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
344e0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
344f0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
34500 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
34510 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
34520 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
34530 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
34540 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
34550 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
34560 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
34570 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
34580 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
34590 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
345a0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
345b0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
345c0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
345d0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
345e0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
345f0 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
34600 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
34610 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
34620 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
34630 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
34640 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
34650 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
34660 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
34670 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
34680 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
34690 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
346a0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
346b0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
346c0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
346d0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
346e0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
346f0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
34700 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
34710 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
34720 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
34730 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
34740 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
34750 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
34760 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
34770 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
34780 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
34790 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
347a0 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
347b0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
347c0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
347d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
347e0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
347f0 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20  using any of.** 
34800 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
34810 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
34820 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20  _prepare_v3()], 
34830 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
34840 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20  16_v2()],.** or 
34850 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
34860 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v3()] or one 
34870 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
34880 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
34890 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
348a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
348b0 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
348c0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
348d0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
348e0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
348f0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
34900 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
34910 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
34920 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
34930 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
34940 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
34950 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
34960 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
34970 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
34980 68 65 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e  he newer "vX" in
34990 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c  terfaces.** [sql
349a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
349b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
349c0 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
349d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
349e0 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  3()],.** [sqlite
349f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
34a00 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
34a10 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
34a20 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
34a30 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
34a40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
34a50 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
34a60 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69  he.** new "vX" i
34a70 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
34a80 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
34a90 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
34aa0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
34ab0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
34ac0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
34ad0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
34ae0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
34af0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
34b00 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
34b10 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
34b20 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
34b30 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
34b40 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
34b50 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
34b60 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
34b70 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
34b80 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
34b90 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
34ba0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
34bb0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
34bc0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
34bd0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
34be0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
34bf0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
34c00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
34c10 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
34c20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
34c30 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
34c40 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
34c50 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
34c60 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
34c70 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
34c80 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
34c90 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
34ca0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
34cb0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
34cc0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
34cd0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
34ce0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
34cf0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
34d00 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
34d10 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
34d20 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
34d30 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
34d40 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
34d50 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
34d60 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
34d70 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
34d80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
34d90 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
34da0 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
34db0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
34dc0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
34dd0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
34de0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
34df0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
34e00 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
34e10 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
34e20 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
34e30 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
34e40 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
34e50 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
34e60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
34e70 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
34e80 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
34e90 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
34ea0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
34eb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
34ec0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
34ed0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
34ee0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
34ef0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
34f00 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
34f10 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
34f20 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
34f30 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
34f40 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
34f50 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
34f60 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
34f70 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
34f80 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
34f90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
34fa0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
34fb0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
34fc0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
34fd0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
34fe0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
34ff0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
35000 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
35010 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
35020 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
35030 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
35040 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
35050 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
35060 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
35070 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
35080 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
35090 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
350a0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
350b0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
350c0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
350d0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
350e0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
350f0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
35100 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
35110 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
35120 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
35130 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
35140 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
35150 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
35160 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
35170 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
35180 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
35190 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
351a0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
351b0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
351c0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
351d0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
351e0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
351f0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
35200 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
35210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
35220 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
35230 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
35240 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
35250 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
35260 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
35270 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
35280 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
35290 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
352a0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
352b0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
352c0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
352d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
352e0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
352f0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
35300 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
35310 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
35320 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
35330 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
35340 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
35350 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
35360 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
35370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
35380 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
35390 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
353a0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
353b0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
353c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
353d0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
353e0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
353f0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
35400 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
35410 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
35420 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
35430 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
35440 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
35450 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
35460 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
35470 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
35480 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
35490 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b 76  ).  But after [v
354a0 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d  ersion 3.6.23.1]
354b0 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33   ([dateof:3.6.23
354c0 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  .1],.** sqlite3_
354d0 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
354e0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
354f0 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
35500 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
35510 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
35520 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
35530 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
35540 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
35550 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
35560 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
35570 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
35580 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
35590 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
355a0 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
355b0 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
355c0 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
355d0 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
355e0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
355f0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
35600 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
35610 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
35620 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
35630 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
35640 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
35650 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
35660 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
35670 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
35680 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
35690 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
356a0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
356b0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
356c0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
356d0 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
356e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
356f0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
35700 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
35710 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
35720 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
35730 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
35740 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
35750 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
35760 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
35770 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
35780 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
35790 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
357a0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
357b0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
357c0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
357d0 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
357e0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
357f0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
35800 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
35810 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
35820 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b  ments.** using [
35830 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
35840 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v3()] or [sqlite
35850 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a  3_prepare_v2()].
35860 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  ** or [sqlite3_p
35870 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
35880 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
35890 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65  re16_v3()] inste
358a0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
358b0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
358c0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
358d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
358e0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
358f0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
35900 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
35910 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
35920 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
35930 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
35940 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
35950 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  e "vX" interface
35960 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  s is recommended
35970 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35980 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
35990 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
359a0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
359b0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
359c0 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48  sult set.** METH
359d0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
359e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
359f0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
35a00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35a10 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
35a20 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
35a30 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
35a40 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
35a50 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
35a60 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
35a70 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
35a80 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
35a90 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
35aa0 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
35ab0 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
35ac0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
35ad0 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
35ae0 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
35af0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
35b00 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
35b10 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
35b20 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
35b30 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
35b40 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
35b50 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
35b60 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
35b70 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
35b80 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
35b90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
35ba0 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
35bb0 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
35bc0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
35bd0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
35be0 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
35bf0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
35c00 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
35c10 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
35c20 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
35c30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
35c40 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
35c50 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
35c60 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
35c70 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
35c80 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
35c90 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
35ca0 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
35cb0 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
35cc0 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
35cd0 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
35ce0 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
35cf0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
35d00 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
35d10 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
35d20 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
35d30 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
35d40 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
35d50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35d60 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
35d70 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
35d80 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
35d90 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
35da0 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
35db0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
35dc0 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
35dd0 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
35de0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
35df0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
35e00 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
35e10 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
35e20 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
35e30 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
35e40 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
35e50 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
35e60 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
35e70 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
35e80 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
35e90 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
35ea0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
35eb0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
35ec0 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
35ed0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
35ee0 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
35ef0 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
35f00 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
35f10 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
35f20 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
35f30 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
35f40 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
35f50 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
35f60 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
35f70 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
35f80 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
35f90 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
35fa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
35fb0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
35fc0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
35fd0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
35fe0 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
35ff0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
36000 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
36010 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
36020 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
36030 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
36040 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
36050 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
36060 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
36070 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
36080 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
36090 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
360a0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
360b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
360c0 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61  t.**.** <b>Summa
360d0 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63  ry:</b>.** <bloc
360e0 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f  kquote><table bo
360f0 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69  rder=0 cellpaddi
36100 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67  ng=0 cellspacing
36110 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  =0>.** <tr><td><
36120 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
36130 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61  _blob</b><td>&ra
36140 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75  rr;<td>BLOB resu
36150 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
36160 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
36170 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72  double</b><td>&r
36180 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73  arr;<td>REAL res
36190 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
361a0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
361b0 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  _int</b><td>&rar
361c0 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54  r;<td>32-bit INT
361d0 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  EGER result.** <
361e0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
361f0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f  3_column_int64</
36200 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
36210 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72  64-bit INTEGER r
36220 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
36230 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
36240 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26  mn_text</b><td>&
36250 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54  rarr;<td>UTF-8 T
36260 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  EXT result.** <t
36270 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
36280 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f  _column_text16</
36290 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
362a0 55 54 46 2d 31 36 20 54 45 58 54 20 72 65 73 75  UTF-16 TEXT resu
362b0 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
362c0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
362d0 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61  value</b><td>&ra
362e0 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c  rr;<td>The resul
362f0 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c  t as an .** [sql
36300 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f  ite3_value|unpro
36310 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
36320 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  alue] object..**
36330 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c   <tr><td>&nbsp;<
36340 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62  td>&nbsp;<td>&nb
36350 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  sp;.** <tr><td><
36360 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
36370 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72  _bytes</b><td>&r
36380 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20  arr;<td>Size of 
36390 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55  a BLOB.** or a U
363a0 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74  TF-8 TEXT result
363b0 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72   in bytes.** <tr
363c0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
363d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e  column_bytes16&n
363e0 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a  bsp;&nbsp;</b>.*
363f0 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73  * <td>&rarr;&nbs
36400 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65  p;&nbsp;<td>Size
36410 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45   of UTF-16.** TE
36420 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c  XT in bytes.** <
36430 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
36440 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62  3_column_type</b
36450 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44  ><td>&rarr;<td>D
36460 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79  efault.** dataty
36470 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  pe of the result
36480 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c  .** </table></bl
36490 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
364a0 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a  <b>Details:</b>.
364b0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
364c0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
364d0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
364e0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
364f0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
36500 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
36510 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
36520 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
36530 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
36540 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
36550 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
36560 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
36570 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
36580 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
36590 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
365a0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
365b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
365c0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
365d0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
365e0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
365f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
36600 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
36610 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
36620 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
36630 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
36640 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
36650 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
36660 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
36670 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
36680 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
36690 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
366a0 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
366b0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
366c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
366d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
366e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
366f0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
36700 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
36710 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
36720 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
36730 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
36740 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
36750 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
36760 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
36770 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
36780 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
36790 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
367a0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
367b0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
367c0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
367d0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
367e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
367f0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
36800 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
36810 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
36820 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
36830 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
36840 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
36850 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
36860 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
36870 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
36880 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
36890 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
368a0 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
368b0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
368c0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
368d0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
368e0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
368f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
36900 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
36910 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
36920 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
36930 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
36940 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
36950 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
36960 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
36970 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
36980 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
36990 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
369a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73 69  .** The first si
369b0 78 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62  x interfaces (_b
369c0 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69  lob, _double, _i
369d0 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78  nt, _int64, _tex
369e0 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a  t, and _text16).
369f0 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20 74  ** each return t
36a00 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65  he value of a re
36a10 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61  sult column in a
36a20 20 73 70 65 63 69 66 69 63 20 64 61 74 61 20 66   specific data f
36a30 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68  ormat.  If.** th
36a40 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  e result column 
36a50 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79  is not initially
36a60 20 69 6e 20 74 68 65 20 72 65 71 75 65 73 74 65   in the requeste
36a70 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78  d format (for ex
36a80 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65  ample,.** if the
36a90 20 71 75 65 72 79 20 72 65 74 75 72 6e 73 20 61   query returns a
36aa0 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20 74 68  n integer but th
36ab0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
36ac0 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66 61 63  _text() interfac
36ad0 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20  e.** is used to 
36ae0 65 78 74 72 61 63 74 20 74 68 65 20 76 61 6c 75  extract the valu
36af0 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d  e) then an autom
36b00 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72  atic type conver
36b10 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
36b20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
36b30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
36b40 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
36b50 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
36b60 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
36b70 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
36b80 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
36b90 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
36ba0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
36bb0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
36bc0 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
36bd0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
36be0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
36bf0 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
36c00 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
36c10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
36c20 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  ]..** The return
36c30 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65   value of sqlite
36c40 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
36c50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
36c60 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f  ecide which.** o
36c70 66 20 74 68 65 20 66 69 72 73 74 20 73 69 78 20  f the first six 
36c80 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64  interface should
36c90 20 62 65 20 75 73 65 64 20 74 6f 20 65 78 74 72   be used to extr
36ca0 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76  act the column v
36cb0 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  alue..** The val
36cc0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
36cd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
36ce0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
36cf0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a  ningful if no.**
36d00 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20   automatic type 
36d10 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
36d20 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74 68   occurred for th
36d30 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74  e value in quest
36d40 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20  ion.  .** After 
36d50 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
36d60 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  n, the result of
36d70 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
36d80 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
36d90 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20  * is undefined, 
36da0 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e  though harmless.
36db0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
36dc0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
36dd0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
36de0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
36df0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
36e00 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
36e10 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
36e20 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  **.** If the res
36e30 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
36e40 20 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20   a TEXT string, 
36e50 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
36e60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
36e70 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ** or sqlite3_co
36e80 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69  lumn_bytes16() i
36e90 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20 62 65  nterfaces can be
36ea0 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69   used to determi
36eb0 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f  ne the size.** o
36ec0 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  f that BLOB or s
36ed0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tring..**.** ^If
36ee0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
36ef0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
36f00 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
36f10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36f20 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
36f30 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
36f40 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
36f50 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
36f60 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
36f70 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
36f80 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
36f90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36fa0 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
36fb0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
36fc0 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
36fd0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
36fe0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
36ff0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
37000 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
37010 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
37020 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
37030 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
37040 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
37050 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
37060 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
37070 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
37080 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
37090 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
370a0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
370b0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
370c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
370d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
370e0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
370f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
37100 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
37110 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
37120 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
37130 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
37140 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
37150 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
37160 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
37170 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
37180 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
37190 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
371a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
371b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
371c0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
371d0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
371e0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
371f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
37200 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
37210 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
37220 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
37230 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37240 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
37250 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
37260 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
37270 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
37280 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
37290 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
372a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
372b0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
372c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
372d0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
372e0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
372f0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
37300 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
37310 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
37320 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
37330 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
37340 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
37350 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
37360 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
37370 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
37380 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
37390 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
373a0 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
373b0 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
373c0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
373d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
373e0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
373f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
37400 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
37410 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
37420 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
37430 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
37440 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
37450 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
37460 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
37470 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
37480 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
37490 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
374a0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
374b0 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
374c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
374d0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
374e0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
374f0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
37500 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
37510 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
37520 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c  pointer..**.** <
37530 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e  b>Warning:</b> ^
37540 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
37550 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
37560 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
37570 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
37580 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
37590 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e  lue] object.  In
375a0 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64   a multithreaded
375b0 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a   environment,.**
375c0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
375d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
375e0 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ject may only be
375f0 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74   used safely wit
37600 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  h.** [sqlite3_bi
37610 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
37620 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
37630 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
37640 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
37650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
37660 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
37670 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
37680 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
37690 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
376a0 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
376b0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
376c0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
376d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
376e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
376f0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
37700 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
37710 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62  _bytes()], the b
37720 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
37730 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65  hreadsafe..** He
37740 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  nce, the sqlite3
37750 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20  _column_value() 
37760 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
37770 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73  normally only us
37780 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20  eful within the 
37790 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
377a0 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69  f .** [applicati
377b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
377c0 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69  unctions] or [vi
377d0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e  rtual tables], n
377e0 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70  ot within.** top
377f0 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69  -level applicati
37800 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54  on code..**.** T
37810 68 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  he these routine
37820 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f  s may attempt to
37830 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74   convert the dat
37840 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73  atype of the res
37850 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61  ult..** ^For exa
37860 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
37870 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
37880 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
37890 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
378a0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
378b0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
378c0 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
378d0 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
378e0 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
378f0 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
37900 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
37910 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
37920 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
37930 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
37940 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
37950 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
37960 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
37970 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
37980 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
37990 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
379a0 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
379b0 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
379c0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
379d0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
379e0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
379f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
37a00 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
37a10 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
37a20 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
37a30 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
37a40 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
37a50 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
37a60 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
37a70 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
37a80 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
37a90 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
37aa0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
37ab0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
37ac0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
37ad0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
37ae0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
37af0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
37b00 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
37b10 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
37b20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
37b30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
37b40 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
37b50 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
37b60 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
37b70 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
37b80 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
37b90 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
37ba0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
37bb0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
37bc0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
37bd0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
37be0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
37bf0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
37c00 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
37c10 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
37c20 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42  > [CAST] to BLOB
37c30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
37c40 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
37c50 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
37c60 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
37c70 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
37c80 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
37c90 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
37ca0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
37cb0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
37cc0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
37cd0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
37ce0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
37cf0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
37d00 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
37d10 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  R.** <tr><td>  B
37d20 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
37d30 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
37d40 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
37d50 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
37d60 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
37d70 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
37d80 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
37d90 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
37da0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
37db0 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ^.**.** Note tha
37dc0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
37dd0 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
37de0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
37df0 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
37e00 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
37e10 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
37e20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
37e30 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
37e40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
37e50 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
37e60 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
37e70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
37e80 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
37e90 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
37ea0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
37eb0 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
37ec0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
37ed0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
37ee0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
37ef0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
37f00 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
37f10 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
37f20 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
37f30 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
37f40 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
37f50 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
37f60 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
37f70 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
37f80 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
37f90 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
37fa0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
37fb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37fc0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
37fd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37fe0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
37ff0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
38000 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
38010 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
38020 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
38030 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
38040 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
38050 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
38060 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
38070 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
38080 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
38090 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
380a0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
380b0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
380c0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
380d0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
380e0 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
380f0 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
38100 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
38110 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
38120 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
38130 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
38140 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
38150 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
38160 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
38170 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
38180 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
38190 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
381a0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
381b0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
381c0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
381d0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
381e0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
381f0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
38200 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
38210 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
38220 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
38230 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
38240 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
38250 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
38260 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69   safest policy i
38270 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
38280 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
38290 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
382a0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
382b0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
382c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
382d0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
382e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
382f0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
38300 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
38310 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
38320 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
38330 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
38340 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
38350 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
38360 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
38370 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
38380 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
38390 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
383a0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
383b0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
383c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
383d0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
383e0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
383f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
38400 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
38410 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
38420 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
38430 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
38440 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
38450 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
38460 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
38470 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
38480 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
38490 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
384a0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
384b0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
384c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
384d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
384e0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
384f0 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
38500 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
38510 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
38520 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
38530 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
38540 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
38550 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
38560 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
38570 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
38580 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
38590 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
385a0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
385b0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
385c0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
385d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
385e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
385f0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
38600 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
38610 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
38620 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
38630 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
38640 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
38650 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
38660 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f  atically.  Do no
38670 74 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  t pass the point
38680 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
38690 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
386a0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
386b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
386c0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
386d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
386e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c  e()]..**.** As l
386f0 6f 6e 67 20 61 73 20 74 68 65 20 69 6e 70 75 74  ong as the input
38700 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
38710 63 6f 72 72 65 63 74 2c 20 74 68 65 73 65 20 72  correct, these r
38720 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 6f 6e 6c  outines will onl
38730 79 0a 2a 2a 20 66 61 69 6c 20 69 66 20 61 6e 20  y.** fail if an