System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 2c1bb961dc5505795b3a7b0913e43d2e3e156eef:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 33 2e 32 37 2e 32 22 0a 23 64 65      "3.27.2".#de
1210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1220: 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 32 37 30  ION_NUMBER 30270
1230: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
1240: 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20  E_SOURCE_ID     
1250: 20 22 32 30 31 39 2d 30 32 2d 32 35 20 31 36 3a   "2019-02-25 16:
1260: 30 36 3a 30 36 20 62 64 34 39 61 38 32 37 31 64  06:06 bd49a8271d
1270: 36 35 30 66 61 38 39 65 34 34 36 62 34 32 65 35  650fa89e446b42e5
1280: 31 33 62 35 39 35 61 37 31 37 62 39 32 31 32 63  13b595a717b9212c
1290: 39 31 64 64 33 38 34 61 61 62 38 37 31 66 63 31  91dd384aab871fc1
12a0: 64 30 66 36 64 37 22 0a 0a 2f 2a 0a 2a 2a 20 43  d0f6d7"../*.** C
12b0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
12c0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
12d0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
12e0: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
12f0: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1300: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1310: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1320: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1330: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1340: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1350: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1360: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1370: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1380: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1390: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
13a0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
13b0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
13c0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
13d0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
13e0: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
13f0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1400: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1410: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1420: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1430: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1440: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1450: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1460: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1470: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1480: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1490: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
14a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14b0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
14c0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
14d0: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
14e0: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
14f0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1500: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1510: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1520: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1530: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1540: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 6e  .** assert( strn
1550: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1560: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1570: 55 52 43 45 5f 49 44 2c 38 30 29 3d 3d 30 20 29  URCE_ID,80)==0 )
1580: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1590: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76  cmp(sqlite3_libv
15a0: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f  ersion(),SQLITE_
15b0: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a  VERSION)==0 );.*
15c0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15d0: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
15e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
15f0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1600: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
1610: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54  e text of [SQLIT
1620: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61  E_VERSION].** ma
1630: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  cro.  ^The sqlit
1640: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
1650: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1660: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1670: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69  e.** to the sqli
1680: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1690: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
16a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
16b0: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63  ersion().** func
16c0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
16d0: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73   for use in DLLs
16e0: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73   since DLL users
16f0: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20   usually do not 
1700: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61  have.** direct a
1710: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20  ccess to string 
1720: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e  constants within
1730: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a   the DLL.  ^The.
1740: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
1750: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66  rsion_number() f
1760: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1770: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c  an integer equal
1780: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56   to.** [SQLITE_V
1790: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
17a0: 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
17b0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
17c0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
17d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
17e0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
17f0: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1800: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1810: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1820: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1830: 6f 72 20 6d 61 63 72 6f 2e 20 20 45 78 63 65 70  or macro.  Excep
1840: 74 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 62  t if SQLite is b
1850: 75 69 6c 74 0a 2a 2a 20 75 73 69 6e 67 20 61 6e  uilt.** using an
1860: 20 65 64 69 74 65 64 20 63 6f 70 79 20 6f 66 20   edited copy of 
1870: 5b 74 68 65 20 61 6d 61 6c 67 61 6d 61 74 69 6f  [the amalgamatio
1880: 6e 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 61 73  n], then the las
1890: 74 20 66 6f 75 72 20 63 68 61 72 61 63 74 65 72  t four character
18a0: 73 0a 2a 2a 20 6f 66 20 74 68 65 20 68 61 73 68  s.** of the hash
18b0: 20 6d 69 67 68 74 20 62 65 20 64 69 66 66 65 72   might be differ
18c0: 65 6e 74 20 66 72 6f 6d 20 5b 53 51 4c 49 54 45  ent from [SQLITE
18d0: 5f 53 4f 55 52 43 45 5f 49 44 5d 2e 29 5e 0a 2a  _SOURCE_ID].)^.*
18e0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
18f0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
1900: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
1910: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1920: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1930: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1940: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1950: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1960: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
1970: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1980: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
1990: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
19a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
19b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
19c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
19d0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
19e0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
19f0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1a00: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
1a10: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
1a20: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
1a30: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
1a40: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
1a50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a60: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
1a70: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
1a80: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
1a90: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
1aa0: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
1ab0: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
1ac0: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
1ad0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
1ae0: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
1af0: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
1b00: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
1b20: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
1b50: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
1b60: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
1b70: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
1b80: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
1b90: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
1ba0: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
1bb0: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
1bc0: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
1bd0: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
1be0: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
1bf0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c00: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
1c10: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1c20: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
1c30: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
1c40: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
1c50: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1c60: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1c70: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
1c80: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
1c90: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
1ca0: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
1cb0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1cc0: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
1cd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ce0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
1cf0: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
1d00: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
1d10: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
1d20: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d30: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
1d40: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
1d50: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
1d60: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
1d70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1d80: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1d90: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
1da0: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
1db0: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
1dc0: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
1dd0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1de0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1df0: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
1e00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1e10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1e20: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1e30: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
1e40: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
1e50: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1e60: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1e70: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1e80: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1e90: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ea0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1eb0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1ec0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1ed0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1ee0: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1ef0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1f00: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1f10: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1f20: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1f30: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1f40: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1f50: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1f60: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1f70: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1f80: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1f90: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1fa0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1fb0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1fc0: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1fd0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1fe0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1ff0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
2000: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
2010: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
2020: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
2030: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
2040: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
2050: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
2060: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
2070: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
2080: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
2090: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
20a0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
20b0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
20c0: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
20d0: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
20e0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
20f0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
2100: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
2110: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
2120: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
2130: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
2140: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
2150: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
2160: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
2170: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
2180: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
2190: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
21a0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
21b0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
21c0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
21d0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
21e0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
21f0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2200: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2210: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2220: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2230: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2240: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2250: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
2260: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
2270: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
2280: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2290: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
22a0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
22b0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
22c0: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
22d0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
22e0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
22f0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2300: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2310: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2320: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2330: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2340: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2350: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2360: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2370: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2380: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2390: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
23a0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
23b0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
23c0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
23d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
23e0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
23f0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2400: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2410: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2420: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2430: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2440: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2450: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2460: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2470: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2480: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2490: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
24a0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
24b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
24c0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
24d0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
24e0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
24f0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2500: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2510: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2520: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2530: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2540: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2550: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2560: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2570: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2580: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2590: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
25a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
25b0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
25c0: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
25d0: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
25e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
25f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2600: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2610: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2620: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2630: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2640: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2650: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2660: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2670: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2680: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2690: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
26a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
26b0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
26c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
26d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
26e0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
26f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2700: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2710: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2720: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2730: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2740: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2750: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
2760: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
2770: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
2780: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
2790: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
27a0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
27b0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27c0: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
27d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
27e0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
27f0: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2800: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2810: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2820: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2830: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2840: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2850: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
2860: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
2870: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
2880: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2890: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
28a0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
28b0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
28c0: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
28d0: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
28e0: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
28f0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2900: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2910: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2920: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2930: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2940: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2950: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2960: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
2970: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
2980: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
2990: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
29a0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
29b0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
29c0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
29d0: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
29e0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
29f0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2a00: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2a10: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2a20: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2a30: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2a40: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2a50: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
2a60: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
2a70: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
2a80: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2a90: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
2aa0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
2ab0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2ac0: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2ad0: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2ae0: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2af0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2b00: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2b30: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2b40: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2b50: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
2b60: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2b70: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
2b80: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2b90: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2ba0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
2bb0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2bc0: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2bd0: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2be0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2bf0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2c00: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c10: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2c30: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2c40: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2c50: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2c60: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2c70: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2c80: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2c90: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ca0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2cb0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2cc0: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2cd0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2ce0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2cf0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2d00: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2d10: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2d20: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2d30: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2d40: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2d50: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2d60: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2d70: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2d80: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2d90: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2da0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2db0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2dc0: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2dd0: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2de0: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2df0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2e00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2e10: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2e20: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2e30: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2e40: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2e50: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2e60: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2e70: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2e80: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2e90: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ea0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2eb0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2ec0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2ed0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2ee0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2ef0: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2f00: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f10: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2f20: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2f30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2f40: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2f50: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2f60: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2f70: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2f80: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2f90: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2fa0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2fb0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2fc0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2fd0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2fe0: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2ff0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
3000: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
3010: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
3020: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
3030: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
3040: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
3050: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
3060: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
3070: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
3080: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
3090: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
30a0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
30b0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
30c0: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
30d0: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
30e0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
30f0: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
3100: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
3110: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
3120: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
3130: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
3140: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
3150: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
3160: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
3170: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
3180: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
3190: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
31a0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
31b0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
31c0: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
31d0: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
31e0: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
31f0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3200: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3210: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3220: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3230: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3240: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3250: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
3260: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3270: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
3280: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
3290: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
32a0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
32b0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
32c0: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
32d0: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
32e0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
32f0: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3300: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3310: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3320: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3330: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3340: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3350: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
3360: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3370: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
3380: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
3390: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
33a0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
33b0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
33c0: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
33d0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
33e0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
33f0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3400: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3410: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3420: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3430: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3440: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3450: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
3460: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
3470: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
3480: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
3490: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
34a0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
34b0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
34c0: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
34d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
34e0: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
34f0: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3500: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3510: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3520: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3530: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3540: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3550: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
3560: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
3570: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
3580: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
3590: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
35a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
35b0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
35c0: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
35d0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
35e0: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
35f0: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
3600: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
3610: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3620: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
3630: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
3640: 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a  e_v2(sqlite3*);.
3650: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
3660: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
3670: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
3680: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
3690: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
36a0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
36b0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
36c0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
36d0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
36e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
36f0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
3700: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
3710: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
3720: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3730: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
3740: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
3750: 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ace.** METHOD: s
3760: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
3770: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3780: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
3790: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
37a0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
37b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
37c0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
37d0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
37e0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
37f0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3800: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3810: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3820: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3830: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3840: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3850: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3860: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3870: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3880: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3890: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
38a0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
38b0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
38c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
38d0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
38e0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
38f0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3900: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3910: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3920: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3930: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3940: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3950: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3960: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3970: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3980: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3990: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
39a0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
39b0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
39c0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
39d0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
39e0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
39f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3a00: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3a10: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3a20: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3a30: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3a40: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3a50: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3a60: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3a70: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3a80: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3a90: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3aa0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3ab0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3ac0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3ad0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3ae0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3af0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3b00: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3b20: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3b30: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3b40: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3b50: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3b60: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3b70: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3b90: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3ba0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3bb0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3bc0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3bd0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3be0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3bf0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3c00: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3c10: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3c20: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3c30: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3c40: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3c50: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3c60: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3c70: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3c80: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3c90: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3ca0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3cb0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69  meter of.** sqli
3cc0: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72  te3_exec() after
3cd0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
3ce0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20  ge string is no 
3cf0: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
3d00: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61  * ^If the 5th pa
3d10: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3d20: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
3d30: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72   NULL and no err
3d40: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68  ors.** occur, th
3d50: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  en sqlite3_exec(
3d60: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74  ) sets the point
3d70: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61  er in its 5th pa
3d80: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55  rameter to.** NU
3d90: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  LL before return
3da0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ing..**.** ^If a
3db0: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3dc0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
3dd0: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
3de0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3df0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
3e00: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77  s SQLITE_ABORT w
3e10: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20  ithout invoking 
3e20: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61  the callback aga
3e30: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75  in and.** withou
3e40: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75  t running any su
3e50: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
3e60: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
3e70: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  The 2nd argument
3e80: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3e90: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3ea0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a  function is the.
3eb0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  ** number of col
3ec0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
3ed0: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72  lt.  ^The 3rd ar
3ee0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3f00: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3f10: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3f20: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61   to strings obta
3f30: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a  ined as if from.
3f40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
3f50: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20  mn_text()], one 
3f60: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  for each column.
3f70: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74    ^If an element
3f80: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20   of a.** result 
3f90: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  row is NULL then
3fa0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
3fb0: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ng string pointe
3fc0: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c  r for the.** sql
3fd0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3fe0: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70  back is a NULL p
3ff0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74  ointer.  ^The 4t
4000: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
4010: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
4020: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
4030: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
4040: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
4050: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e  where each.** en
4060: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74  try represents t
4070: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65  he name of corre
4080: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20  sponding result 
4090: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e  column as obtain
40a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
40b0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
40c0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  )]..**.** ^If th
40d0: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
40e0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
40f0: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
4100: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ter, a pointer.*
4110: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  * to an empty st
4120: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74  ring, or a point
4130: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  er that contains
4140: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
4150: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20   and/or .** SQL 
4160: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
4170: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
4180: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
4190: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  nd the database.
41a0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
41b0: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63  d..**.** Restric
41c0: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tions:.**.** <ul
41d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  >.** <li> The ap
41e0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65  plication must e
41f0: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31  nsure that the 1
4200: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4210: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
4220: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69  *      is a vali
4230: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61  d and open [data
4240: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4250: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
4260: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
4270: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61  ot close the [da
4280: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4290: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  n] specified by.
42a0: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20  **      the 1st 
42b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
42c0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
42d0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
42e0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
42f0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
4300: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f  tion must not mo
4310: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61  dify the SQL sta
4320: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73  tement text pass
4330: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20  ed into.**      
4340: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
4350: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  r of sqlite3_exe
4360: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
4370: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
4380: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ing..** </ul>.*/
4390: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
43a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
43b0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
43e0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
43f0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
4400: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
4410: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4420: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
4430: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  uated */.  int (
4440: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
4450: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
4460: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
4470: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
4480: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
4490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
44b0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
44c0: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
44d0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
44e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44f0: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
4500: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
4510: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
4520: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
4530: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4540: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64  : {result code d
4550: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4560: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
4570: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4580: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4590: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
45a0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
45b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
45c0: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
45d0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
45e0: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
45f0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4600: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4610: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4620: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65   See also: [exte
4630: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4640: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f   definitions].*/
4650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4660: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
4670: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
4680: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
4690: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
46a0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
46b0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
46c0: 20 20 20 20 31 20 20 20 2f 2a 20 47 65 6e 65 72      1   /* Gener
46d0: 69 63 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ic error */.#def
46e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
46f0: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
4700: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
4710: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
4720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4730: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
4740: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
4750: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
4760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4770: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
4780: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
4790: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
47a0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
47c0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
47d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
47e0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
47f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
4800: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
4810: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
4820: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
4830: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4840: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
4850: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
4860: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
4880: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
4890: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
48a0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
48b0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
48c0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
48d0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
48e0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
48f0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
4900: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
4910: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
4920: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
4930: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4940: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4960: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
4970: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4980: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
4990: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
49a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49b0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
49c0: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
49d0: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
49e0: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
49f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
4a00: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
4a10: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
4a20: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
4a30: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4a50: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
4a60: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
4a70: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
4a80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a90: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
4aa0: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
4ab0: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
4ac0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4ad0: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
4ae0: 20 20 31 36 20 20 20 2f 2a 20 49 6e 74 65 72 6e    16   /* Intern
4af0: 61 6c 20 75 73 65 20 6f 6e 6c 79 20 2a 2f 0a 23  al use only */.#
4b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
4b10: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
4b20: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
4b30: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
4b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b50: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
4b60: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
4b70: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
4b80: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
4b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
4ba0: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
4bb0: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
4bc0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4be0: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
4bf0: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
4c00: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
4c10: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
4c20: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
4c30: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
4c40: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
4c50: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
4c60: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
4c70: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
4c80: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
4c90: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
4ca0: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
4cb0: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
4cc0: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
4cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ce0: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
4cf0: 20 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a   /* Not used */.
4d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d10: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4d20: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4d30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4d40: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d60: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4d70: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4d80: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4d90: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4db0: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
4dc0: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
4dd0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4de0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4df0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
4e00: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
4e10: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4e20: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4e30: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4e40: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4e50: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4e60: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4e70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4e80: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4e90: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4ea0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4eb0: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4ec0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4ed0: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4ee0: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4ef0: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
4f00: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4f10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4f20: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4f30: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4f40: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4f50: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4f60: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4f70: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
4f80: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
4f90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4fa0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4fb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4fc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4fd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4fe0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4ff0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
5000: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
5010: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
5020: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
5030: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
5040: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
5050: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
5060: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
5070: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
5080: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61  ersion 3.3.8 [da
5090: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61  teof:3.3.8].** a
50a0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
50b0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
50c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
50d0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
50e0: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
50f0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
5100: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
5110: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
5120: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
5130: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
5140: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
5150: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
5160: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
5170: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
5180: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
5190: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
51a0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
51b0: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
51c0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
51d0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
51e0: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
51f0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
5200: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
5220: 52 4f 52 5f 4d 49 53 53 49 4e 47 5f 43 4f 4c 4c  ROR_MISSING_COLL
5230: 53 45 51 20 20 20 28 53 51 4c 49 54 45 5f 45 52  SEQ   (SQLITE_ER
5240: 52 4f 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ROR | (1<<8)).#d
5250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
5260: 4f 52 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  OR_RETRY        
5270: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 45 52 52       (SQLITE_ERR
5280: 4f 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  OR | (2<<8)).#de
5290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
52a0: 52 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  R_SNAPSHOT      
52b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 45 52 52 4f      (SQLITE_ERRO
52c0: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5310: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5320: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
5330: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5340: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
5360: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
5370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5380: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5390: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
53a0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
53b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53c0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
53e0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5400: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
5420: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
5440: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
5460: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
5480: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5490: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
54a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
54b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
54c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
54d0: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
54e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5500: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5510: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5520: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5530: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
5540: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5550: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
5560: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5570: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
5580: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5590: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
55a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
55c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55d0: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
55e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55f0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5600: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5610: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5620: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
5630: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
5640: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5650: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
5660: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5670: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
5680: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5690: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
56a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
56b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
56c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
56d0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
56e0: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
56f0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5700: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5710: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5720: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5730: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
5740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5750: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
5760: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5770: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
5780: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5790: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
57a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57b0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
57c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57d0: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
57e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57f0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5800: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5810: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5820: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5830: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5850: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
5860: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
5870: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
5880: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5890: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
58a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
58b0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
58c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58d0: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
58e0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58f0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5900: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5910: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5920: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5930: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
5940: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5950: 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20  E_IOERR_VNODE   
5960: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5970: 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38  E_IOERR | (27<<8
5980: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5990: 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20  E_IOERR_AUTH    
59a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
59b0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38  E_IOERR | (28<<8
59c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
59d0: 45 5f 49 4f 45 52 52 5f 42 45 47 49 4e 5f 41 54  E_IOERR_BEGIN_AT
59e0: 4f 4d 49 43 20 20 20 20 20 20 28 53 51 4c 49 54  OMIC      (SQLIT
59f0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 39 3c 3c 38  E_IOERR | (29<<8
5a00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a10: 45 5f 49 4f 45 52 52 5f 43 4f 4d 4d 49 54 5f 41  E_IOERR_COMMIT_A
5a20: 54 4f 4d 49 43 20 20 20 20 20 28 53 51 4c 49 54  TOMIC     (SQLIT
5a30: 45 5f 49 4f 45 52 52 20 7c 20 28 33 30 3c 3c 38  E_IOERR | (30<<8
5a40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a50: 45 5f 49 4f 45 52 52 5f 52 4f 4c 4c 42 41 43 4b  E_IOERR_ROLLBACK
5a60: 5f 41 54 4f 4d 49 43 20 20 20 28 53 51 4c 49 54  _ATOMIC   (SQLIT
5a70: 45 5f 49 4f 45 52 52 20 7c 20 28 33 31 3c 3c 38  E_IOERR | (31<<8
5a80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a90: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
5aa0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
5ab0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
5ac0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ad0: 54 45 5f 4c 4f 43 4b 45 44 5f 56 54 41 42 20 20  TE_LOCKED_VTAB  
5ae0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5af0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 32 3c  TE_LOCKED |  (2<
5b00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b10: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5b20: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5b30: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5b40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b50: 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48  LITE_BUSY_SNAPSH
5b60: 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51  OT           (SQ
5b70: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5b80: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b90: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
5ba0: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
5bb0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5bc0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5bd0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5be0: 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20  _ISDIR          
5bf0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5c00: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5c20: 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20  EN_FULLPATH     
5c30: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5c40: 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  EN | (3<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5c60: 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20  OPEN_CONVPATH   
5c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5c80: 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OPEN | (4<<8)).#
5c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5ca0: 4e 54 4f 50 45 4e 5f 44 49 52 54 59 57 41 4c 20  NTOPEN_DIRTYWAL 
5cb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5cc0: 4e 54 4f 50 45 4e 20 7c 20 28 35 3c 3c 38 29 29  NTOPEN | (5<<8))
5cd0: 20 2f 2a 20 4e 6f 74 20 55 73 65 64 20 2a 2f 0a   /* Not Used */.
5ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5cf0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5d00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5d10: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 43 4f 52 52 55 50 54 5f 53 45 51 55 45 4e 43 45  CORRUPT_SEQUENCE
5d40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5d50: 43 4f 52 52 55 50 54 20 7c 20 28 32 3c 3c 38 29  CORRUPT | (2<<8)
5d60: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d70: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5d80: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5d90: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5da0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5db0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5dc0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5dd0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5de0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5df0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5e00: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
5e10: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5e20: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5e30: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5e40: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
5e50: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5e60: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5e70: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5e80: 59 5f 43 41 4e 54 49 4e 49 54 20 20 20 20 20 20  Y_CANTINIT      
5e90: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5ea0: 59 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  Y | (5<<8)).#def
5eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5ec0: 4e 4c 59 5f 44 49 52 45 43 54 4f 52 59 20 20 20  NLY_DIRECTORY   
5ed0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ee0: 4e 4c 59 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  NLY | (6<<8)).#d
5ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
5f00: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
5f10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
5f20: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
5f30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f40: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
5f50: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5f60: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
5f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f80: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
5f90: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
5fa0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
5fb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5fd0: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
5fe0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ff0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
6000: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6010: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
6020: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6030: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
6040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6050: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
6060: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6070: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
6080: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6090: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
60a0: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
60b0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
60c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
60d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
60e0: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
60f0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6100: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
6110: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6120: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
6130: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6140: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
6150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6160: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
6170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6180: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
6190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61a0: 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44  CONSTRAINT_ROWID
61b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
61c0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c  CONSTRAINT |(10<
61d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
61e0: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56  ITE_NOTICE_RECOV
61f0: 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c  ER_WAL      (SQL
6200: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c  ITE_NOTICE | (1<
6210: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6220: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56  ITE_NOTICE_RECOV
6230: 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c  ER_ROLLBACK (SQL
6240: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c  ITE_NOTICE | (2<
6250: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6260: 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f  ITE_WARNING_AUTO
6270: 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c  INDEX       (SQL
6280: 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31  ITE_WARNING | (1
6290: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
62a0: 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20  LITE_AUTH_USER  
62b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
62c0: 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c  LITE_AUTH | (1<<
62d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
62e0: 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41  TE_OK_LOAD_PERMA
62f0: 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51 4c 49  NENTLY     (SQLI
6300: 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29 29 0a  TE_OK | (1<<8)).
6310: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6320: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20   Flags For File 
6330: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a  Open Operations.
6340: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
6350: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
6360: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
6370: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  he.** 3rd parame
6380: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
6390: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
63a0: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
63b0: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
63c0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
63d0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
63e0: 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69  method..*/.#defi
63f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
6400: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
6410: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
6420: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6430: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6440: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
6450: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
6460: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
6470: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6480: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6490: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
64a0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
64b0: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
64c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
64d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
64e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
64f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
6500: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
6510: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6520: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
6530: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
6540: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
6550: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6560: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
6570: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
6580: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
6590: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
65a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  ne SQLITE_OPEN_U
65b0: 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RI              
65c0: 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f  0x00000040  /* O
65d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
65e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
65f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6600: 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20  EMORY           
6610: 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f  0x00000080  /* O
6620: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6630: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6640: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6650: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
6660: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
6670: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6680: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
6690: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
66a0: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
66b0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
66c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
66d0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
66e0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
66f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6700: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6710: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
6720: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
6730: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6740: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
6750: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
6760: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
6770: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6780: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
6790: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
67a0: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
67b0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
67c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
67d0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
67e0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
67f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6800: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
6810: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
6820: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
6830: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6840: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
6860: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
6870: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
6880: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6890: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
68a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
68b0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
68c0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
68d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
68e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
6900: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
6910: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
6920: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6930: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6940: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57  ne SQLITE_OPEN_W
6950: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AL              
6960: 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56  0x00080000  /* V
6970: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52  FS only */../* R
6980: 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20  eserved:        
6990: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
69a0: 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a   0x00F00000 */..
69b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
69c0: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
69d0: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
69e0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
69f0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f  ristics method o
6a00: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
6a10: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
6a20: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
6a30: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
6a40: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
6a50: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
6a60: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
6a70: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
6a80: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
6a90: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
6aa0: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
6ab0: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
6ac0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6ad0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
6ae0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
6af0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
6b00: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
6b10: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
6b20: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
6b30: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6b40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
6b50: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
6b60: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
6b70: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
6b80: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
6b90: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
6ba0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
6bb0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
6bc0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
6bd0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
6be0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6bf0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6c00: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
6c10: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
6c20: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
6c30: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
6c40: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
6c50: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
6c60: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
6c70: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
6c80: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
6c90: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
6ca0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6cb0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
6cc0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6cd0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
6ce0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
6cf0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
6d00: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
6d10: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20   xWrite().  The 
6d20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6d30: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6d40: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6d50: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65  that.** after re
6d60: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  boot following a
6d70: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20   crash or power 
6d80: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62  loss, the only b
6d90: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c  ytes in a.** fil
6da0: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74  e that were writ
6db0: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69  ten at the appli
6dc0: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67  cation level mig
6dd0: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a  ht have changed.
6de0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61  ** and that adja
6df0: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e  cent bytes, even
6e00: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68   bytes within th
6e10: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72  e same sector ar
6e20: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20  e.** guaranteed 
6e30: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e  to be unchanged.
6e40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6e50: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
6e60: 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67  HEN_OPEN.** flag
6e70: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6e80: 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  a file cannot be
6e90: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70   deleted when op
6ea0: 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49  en.  The.** SQLI
6eb0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
6ec0: 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  LE flag indicate
6ed0: 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20  s that the file 
6ee0: 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e  is on.** read-on
6ef0: 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e  ly media and can
6f00: 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65  not be changed e
6f10: 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73  ven by processes
6f20: 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65   with.** elevate
6f30: 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2a  d privileges..**
6f40: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
6f50: 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49  OCAP_BATCH_ATOMI
6f60: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
6f70: 20 74 68 61 74 20 74 68 65 20 75 6e 64 65 72 6c   that the underl
6f80: 79 69 6e 67 0a 2a 2a 20 66 69 6c 65 73 79 73 74  ying.** filesyst
6f90: 65 6d 20 73 75 70 70 6f 72 74 73 20 64 6f 69 6e  em supports doin
6fa0: 67 20 6d 75 6c 74 69 70 6c 65 20 77 72 69 74 65  g multiple write
6fb0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 74 6f 6d   operations atom
6fc0: 69 63 61 6c 6c 79 20 77 68 65 6e 20 74 68 6f 73  ically when thos
6fd0: 65 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61  e.** write opera
6fe0: 74 69 6f 6e 73 20 61 72 65 20 62 72 61 63 6b 65  tions are bracke
6ff0: 74 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 46  ted by [SQLITE_F
7000: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
7010: 43 5f 57 52 49 54 45 5d 20 61 6e 64 0a 2a 2a 20  C_WRITE] and.** 
7020: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
7030: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
7040: 45 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  E]..*/.#define S
7050: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7060: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
7070: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
7080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7090: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
70a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
70b0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
70c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70d0: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
70e0: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
70f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7100: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
7110: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7120: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
7130: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
7140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7150: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
7160: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7170: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
7180: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
71b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
71c0: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
71d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
71e0: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
71f0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
7200: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7210: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
7220: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7230: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
7240: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
7250: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
7260: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
7270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7280: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
7290: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
72a0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
72b0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
72c0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
72d0: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
72e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
72f0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
7300: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30  ITE    0x0000100
7310: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7320: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
7330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7340: 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65  00002000.#define
7350: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
7360: 54 43 48 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  TCH_ATOMIC      
7370: 20 20 20 20 20 30 78 30 30 30 30 34 30 30 30 0a       0x00004000.
7380: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7390: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
73a0: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
73b0: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
73c0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
73d0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
73e0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
73f0: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
7400: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
7410: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
7420: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
7430: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7440: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
7450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7460: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
7470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7480: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
7490: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
74a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
74b0: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
74c0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
74d0: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
74e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
74f0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
7500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7510: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
7520: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
7530: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
7540: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
7550: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
7560: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7570: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
7580: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
7590: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
75a0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
75b0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
75c0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
75d0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
75e0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
75f0: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
7600: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
7610: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
7620: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
7630: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
7640: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
7650: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
7660: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
7670: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
7680: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
7690: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
76a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
76b0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
76c0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
76d0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
76e0: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
76f0: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
7700: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
7710: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
7720: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
7730: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
7740: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
7750: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
7760: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
7770: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7780: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7790: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
77a0: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
77b0: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
77c0: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
77d0: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
77e0: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
77f0: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
7800: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
7810: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
7820: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
7830: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
7840: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
7850: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
7860: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
7870: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7880: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7890: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
78a0: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
78b0: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
78c0: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
78d0: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
78e0: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
78f0: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
7900: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
7910: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
7920: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
7930: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
7940: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7950: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
7960: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
7970: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
7980: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7990: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
79a0: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
79b0: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
79c0: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
79d0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
79e0: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
79f0: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
7a00: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
7a10: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
7a20: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7a30: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
7a40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7a50: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
7a60: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
7a70: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7a80: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
7a90: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
7aa0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7ab0: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
7ac0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
7ad0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7ae0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
7af0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
7b00: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
7b10: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
7b20: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7b30: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7b40: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
7b50: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
7b60: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7b70: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
7b80: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
7b90: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
7ba0: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
7bb0: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
7bc0: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
7bd0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
7be0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7bf0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
7c00: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
7c10: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
7c20: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7c30: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7c40: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7c50: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
7c60: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7c70: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7c80: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
7c90: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7ca0: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
7cb0: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
7cc0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
7cd0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7ce0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7cf0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
7d00: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
7d10: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
7d20: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7d30: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7d40: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
7d50: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
7d60: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
7d70: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
7d80: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
7d90: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7da0: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
7db0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7dc0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
7dd0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
7de0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7df0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
7e00: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
7e10: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
7e20: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7e30: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7e40: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
7e50: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7e60: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7e70: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7e80: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
7e90: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7ea0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7eb0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
7ec0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
7ed0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
7ee0: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
7ef0: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
7f00: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
7f10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7f20: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7f30: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7f40: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
7f50: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
7f60: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7f70: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
7f80: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
7f90: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
7fa0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7fb0: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7fc0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7fd0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7fe0: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
7ff0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
8000: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
8010: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
8020: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
8030: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
8040: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
8050: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
8060: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
8070: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
8080: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
8090: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
80a0: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
80b0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
80c0: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
80d0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
80e0: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
80f0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
8100: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
8110: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
8120: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
8130: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
8140: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
8150: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
8160: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
8170: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8180: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
8190: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
81a0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
81b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
81c0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
81d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
81e0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
81f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8200: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
8210: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
8220: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
8230: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
8240: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
8250: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
8260: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
8270: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
8280: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
8290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
82a0: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
82b0: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
82c0: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
82d0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
82e0: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
82f0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
8300: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
8310: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
8320: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
8330: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
8340: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
8350: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
8360: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
8370: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
8380: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
8390: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
83a0: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
83b0: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
83c0: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
83d0: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
83e0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
83f0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
8400: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
8410: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
8420: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
8430: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
8440: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
8450: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
8460: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
8470: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
8480: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
8490: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
84a0: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
84b0: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
84c0: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
84d0: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
84e0: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
84f0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
8500: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
8510: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
8520: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
8530: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
8540: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
8550: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
8560: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
8570: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
8580: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
8590: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
85a0: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
85b0: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
85c0: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
85d0: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
85e0: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
85f0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
8600: 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20  use..** A [file 
8610: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
8620: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
8630: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
8640: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
8650: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
8660: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
8670: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
8680: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
8690: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
86a0: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
86b0: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
86c0: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  s.  VFS implemen
86d0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a  tations should.*
86e0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
86f0: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66  _NOTFOUND] for f
8700: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8710: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f  des that they do
8720: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a   not.** recogniz
8730: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
8740: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
8750: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
8760: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
8770: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
8780: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
8790: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
87a0: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
87b0: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
87c0: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
87d0: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
87e0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
87f0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
8800: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
8810: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
8820: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
8830: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
8840: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
8850: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
8860: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
8870: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
8880: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8890: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
88a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
88b0: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
88c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
88d0: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
88e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
88f0: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
8900: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8910: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
8920: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8930: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
8940: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8950: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
8960: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8970: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
8980: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8990: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
89a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
89b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
89c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
89d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
89e0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  L].** <li> [SQLI
89f0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
8a00: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a  ABLE_WHEN_OPEN].
8a10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8a20: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
8a30: 4f 56 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c  OVERWRITE].** <l
8a40: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8a50: 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c  _IMMUTABLE].** <
8a60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8a70: 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 5d 0a  P_BATCH_ATOMIC].
8a80: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
8a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8aa0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
8ab0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
8ac0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
8ad0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
8ae0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8af0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
8b00: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
8b10: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
8b20: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
8b30: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8b40: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8b50: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8b60: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8b70: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8b80: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
8b90: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8ba0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
8bb0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
8bc0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
8bd0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
8be0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
8bf0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
8c00: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
8c10: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
8c20: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
8c30: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8c40: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8c50: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8c60: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8c70: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8c80: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8c90: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
8ca0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
8cb0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
8cc0: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8cd0: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
8ce0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
8cf0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
8d00: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
8d10: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
8d20: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
8d30: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8d40: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8d50: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8d60: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8d70: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8d80: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8d90: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
8da0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
8db0: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
8dc0: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8dd0: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
8de0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8df0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8e00: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
8e10: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
8e20: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8e30: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8e40: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8e50: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8e60: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8e70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8e80: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8e90: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8ea0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8eb0: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
8ec0: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8ed0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8ee0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8ef0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
8f00: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
8f10: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8f20: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
8f30: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8f40: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8f50: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8f60: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8f70: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8f80: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8f90: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8fa0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8fb0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8fc0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8fd0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8fe0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
8ff0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
9000: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
9010: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
9020: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
9030: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
9040: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
9050: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
9060: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
9070: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
9080: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
9090: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
90a0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
90b0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
90c0: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
90d0: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
90e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
90f0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
9100: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
9110: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
9120: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
9130: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
9140: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
9150: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
9160: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
9170: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
9180: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
9190: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
91a0: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
91b0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
91c0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
91d0: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
91e0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
91f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
9200: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
9210: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
9220: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
9230: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
9240: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
9250: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
9260: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
9270: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9280: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9290: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
92a0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
92b0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
92c0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
92d0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
92e0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
92f0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
9300: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
9310: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
9320: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
9330: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
9340: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
9350: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
9360: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
9370: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
9380: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
9390: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
93a0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
93b0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
93c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
93d0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
93e0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
93f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
9400: 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65  CKSTATE]].** The
9410: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
9420: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
9430: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
9440: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
9450: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
9460: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
9470: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
9480: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
9490: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
94a0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
94b0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
94c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
94d0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
94e0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
94f0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
9500: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
9510: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
9520: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
9530: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
9540: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
9550: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
9560: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
9570: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
9580: 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  and is only avai
9590: 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53  lable when the S
95a0: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f  QLITE_TEST.** co
95b0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
95c0: 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
95d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
95e0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
95f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9600: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
9610: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
9620: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
9630: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
9640: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
9650: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
9660: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
9670: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
9680: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
9690: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
96a0: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
96b0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
96c0: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
96d0: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
96e0: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
96f0: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
9700: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
9710: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
9720: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
9730: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
9740: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
9750: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
9760: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
9770: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
9780: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9790: 53 49 5a 45 5f 4c 49 4d 49 54 5d 5d 0a 2a 2a 20  SIZE_LIMIT]].** 
97a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
97b0: 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 6f 70  L_SIZE_LIMIT] op
97c0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
97d0: 69 6e 2d 6d 65 6d 6f 72 79 20 56 46 53 20 74 68  in-memory VFS th
97e0: 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 73  at.** implements
97f0: 20 5b 73 71 6c 69 74 65 33 5f 64 65 73 65 72 69   [sqlite3_deseri
9800: 61 6c 69 7a 65 28 29 5d 20 74 6f 20 73 65 74 20  alize()] to set 
9810: 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
9820: 6e 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66  n the size.** of
9830: 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 64   the in-memory d
9840: 61 74 61 62 61 73 65 2e 20 20 54 68 65 20 61 72  atabase.  The ar
9850: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9860: 74 65 72 20 74 6f 20 61 20 5b 73 71 6c 69 74 65  ter to a [sqlite
9870: 33 5f 69 6e 74 36 34 5d 2e 0a 2a 2a 20 49 66 20  3_int64]..** If 
9880: 74 68 65 20 69 6e 74 65 67 65 72 20 70 6f 69 6e  the integer poin
9890: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
98a0: 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 66  ve, then it is f
98b0: 69 6c 6c 65 64 20 69 6e 20 77 69 74 68 20 74 68  illed in with th
98c0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6c 69 6d  e.** current lim
98d0: 69 74 2e 20 20 4f 74 68 65 72 77 69 73 65 20 74  it.  Otherwise t
98e0: 68 65 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20  he limit is set 
98f0: 74 6f 20 74 68 65 20 6c 61 72 67 65 72 20 6f 66  to the larger of
9900: 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
9910: 20 74 68 65 20 69 6e 74 65 67 65 72 20 70 6f 69   the integer poi
9920: 6e 74 65 64 20 74 6f 20 61 6e 64 20 74 68 65 20  nted to and the 
9930: 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
9940: 20 73 69 7a 65 2e 20 20 54 68 65 20 69 6e 74 65   size.  The inte
9950: 67 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ger.** pointed t
9960: 6f 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20  o is set to the 
9970: 6e 65 77 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a  new limit..**.**
9980: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9990: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
99a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
99b0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
99c0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
99d0: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
99e0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
99f0: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9a00: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9a10: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9a20: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
9a30: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
9a40: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
9a50: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
9a60: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9a70: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
9a80: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
9a90: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
9aa0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
9ab0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9ac0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9ad0: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9ae0: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9af0: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9b00: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9b10: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9b20: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
9b30: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
9b40: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
9b50: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
9b60: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
9b70: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
9b80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b90: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
9ba0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9bb0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9bc0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9bd0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9be0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9bf0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9c00: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9c10: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9c20: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9c30: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9c40: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9c50: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
9c60: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ER]..**.** <li>[
9c70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
9c80: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a  URNAL_POINTER]].
9c90: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9ca0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9cb0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9cc0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9cd0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9ce0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9cf0: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9d00: 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75  ted with the jou
9d10: 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65  rnal file (eithe
9d20: 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61  r.** the [rollba
9d30: 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74  ck journal] or t
9d40: 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20  he [write-ahead 
9d50: 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74  log]) for a part
9d60: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
9d70: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9d80: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
9d90: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9da0: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
9db0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9dc0: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9dd0: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9de0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9df0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9e00: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9e10: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
9e20: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9e30: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
9e40: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
9e50: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
9e60: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
9e70: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
9e80: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
9e90: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
9ea0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
9eb0: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9ec0: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9ed0: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9ee0: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9ef0: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9f00: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9f10: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
9f20: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9f30: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
9f40: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
9f50: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
9f60: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
9f70: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
9f80: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
9f90: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9fa0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9fb0: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9fc0: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9fd0: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9fe0: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9ff0: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
a000: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
a010: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
a020: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
a030: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
a040: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
a050: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
a060: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
a070: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
a080: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
a090: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
a0a0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
a0b0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
a0c0: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
a0d0: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
a0e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a0f0: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
a100: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
a110: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
a120: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
a130: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
a140: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
a150: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
a160: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
a170: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
a180: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
a190: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a1a0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
a1b0: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
a1c0: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
a1d0: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
a1e0: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
a1f0: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
a200: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
a210: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
a220: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
a230: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
a240: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
a250: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
a260: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
a270: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
a280: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
a290: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
a2a0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
a2b0: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
a2c0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a2d0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
a2e0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
a2f0: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
a300: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
a310: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
a320: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
a330: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
a340: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a350: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
a360: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
a370: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
a380: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
a390: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
a3a0: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
a3b0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
a3c0: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
a3d0: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
a3e0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
a3f0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
a400: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
a410: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
a420: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
a430: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
a440: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
a450: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
a460: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
a470: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
a480: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
a490: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
a4a0: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
a4b0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
a4c0: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
a4d0: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
a4e0: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
a4f0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
a500: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
a510: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
a520: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
a530: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
a540: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
a550: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
a560: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
a570: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
a580: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
a590: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
a5a0: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
a5b0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
a5c0: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
a5d0: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
a5e0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
a5f0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
a600: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
a610: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
a620: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
a630: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
a640: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
a650: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
a660: 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  s the new retry 
a670: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
a680: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
a690: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
a6a0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
a6b0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
a6c0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
a6d0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
a6e0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
a6f0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
a700: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
a710: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
a720: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
a730: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
a740: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
a750: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
a760: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
a770: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
a780: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
a790: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a7a0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a7b0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
a7c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a7d0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
a7e0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a7f0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a800: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
a810: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
a820: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
a830: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
a840: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
a850: 68 65 61 64 20 6c 6f 67 20 28 5b 57 41 4c 20 66  head log ([WAL f
a860: 69 6c 65 5d 29 20 61 6e 64 20 73 68 61 72 65 64  ile]) and shared
a870: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 69 6c 65 73   memory.** files
a880: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
a890: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
a8a0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
a8b0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
a8c0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
a8d0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
a8e0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
a8f0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
a900: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
a910: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
a920: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
a930: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
a940: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
a950: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
a960: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
a970: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
a980: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
a990: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
a9a0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
a9b0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
a9c0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
a9d0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
a9e0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
a9f0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
aa00: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
aa10: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
aa20: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
aa30: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
aa40: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
aa50: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
aa60: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
aa70: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
aa80: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
aa90: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
aaa0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
aab0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
aac0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
aad0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
aae0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
aaf0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
ab00: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
ab10: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
ab20: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
ab30: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
ab40: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
ab50: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
ab60: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
ab70: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
ab80: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
ab90: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
aba0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
abb0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
abc0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
abd0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
abe0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
abf0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
ac00: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
ac10: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
ac20: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
ac30: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
ac40: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
ac50: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
ac60: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
ac70: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
ac80: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
ac90: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
aca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
acb0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
acc0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
acd0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
ace0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
acf0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
ad00: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
ad10: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
ad20: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
ad30: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
ad40: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
ad50: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
ad60: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
ad70: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
ad80: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
ad90: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
ada0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
adb0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
adc0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
add0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
ade0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
adf0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
ae00: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
ae10: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
ae20: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
ae30: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
ae40: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
ae50: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
ae60: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
ae70: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
ae80: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
ae90: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
aea0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
aeb0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
aec0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
aed0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
aee0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aef0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
af00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
af10: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
af20: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
af30: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
af40: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
af50: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
af60: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
af70: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
af80: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
af90: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
afa0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
afb0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
afc0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
afd0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
afe0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
aff0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
b000: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
b010: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
b020: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
b030: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
b040: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
b050: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
b060: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
b070: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
b080: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
b090: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
b0a0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
b0b0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
b0c0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
b0d0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
b0e0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
b0f0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
b100: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
b110: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
b120: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
b130: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
b140: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
b150: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
b160: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
b170: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
b180: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
b190: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
b1a0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
b1b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
b1c0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
b1d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b1e0: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
b1f0: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
b200: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
b210: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
b220: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
b230: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
b240: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
b250: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b260: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
b270: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
b280: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
b290: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
b2a0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
b2b0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
b2c0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
b2d0: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
b2e0: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
b2f0: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
b300: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
b310: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
b320: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
b330: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
b340: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
b350: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b360: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
b370: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
b380: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
b390: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
b3a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b3b0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
b3c0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
b3d0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
b3e0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
b3f0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
b400: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
b410: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
b420: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
b430: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
b440: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
b450: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b460: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b470: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
b480: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
b490: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
b4a0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
b4b0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
b4c0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
b4d0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
b4e0: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
b4f0: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
b500: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
b510: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
b520: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
b530: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
b540: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
b550: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
b560: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b570: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b580: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
b590: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
b5a0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
b5b0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
b5c0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
b5d0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
b5e0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
b5f0: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
b600: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
b610: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
b620: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
b630: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
b640: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
b650: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
b660: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
b670: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
b680: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b690: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b6a0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
b6b0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
b6c0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
b6d0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
b6e0: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
b6f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b700: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b710: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b720: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
b730: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
b740: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
b750: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
b760: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
b770: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
b780: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
b790: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
b7a0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
b7b0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
b7c0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
b7d0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
b7e0: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
b7f0: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
b800: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
b810: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
b820: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b830: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b840: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
b850: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
b860: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
b870: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
b880: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
b890: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
b8a0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
b8b0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
b8c0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
b8d0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
b8e0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
b8f0: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
b900: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
b910: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b920: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b930: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
b940: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
b950: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
b960: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
b970: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
b980: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
b990: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
b9a0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
b9b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b9c0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
b9d0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
b9e0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b9f0: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
ba00: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
ba10: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
ba20: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
ba30: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
ba40: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
ba50: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
ba60: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
ba70: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
ba80: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
ba90: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
baa0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
bab0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
bac0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
bad0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
bae0: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
baf0: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
bb00: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
bb10: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
bb20: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
bb30: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
bb40: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
bb50: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
bb60: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
bb70: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
bb80: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
bb90: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
bba0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
bbb0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
bbc0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
bbd0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
bbe0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
bbf0: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
bc00: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
bc10: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
bc20: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
bc30: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
bc40: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
bc50: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
bc60: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
bc70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
bc80: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
bc90: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
bca0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
bcb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
bcc0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
bcd0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
bce0: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
bcf0: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
bd00: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
bd10: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
bd20: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
bd30: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
bd40: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
bd50: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
bd60: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
bd70: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
bd80: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
bd90: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
bda0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
bdb0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
bdc0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
bdd0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
bde0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
bdf0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
be00: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
be10: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
be20: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
be30: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
be40: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
be50: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
be60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
be70: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
be80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
be90: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
bea0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
beb0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
bec0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
bed0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
bee0: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
bef0: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
bf00: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
bf10: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
bf20: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
bf30: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
bf40: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
bf50: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
bf60: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
bf70: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
bf80: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
bf90: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
bfa0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
bfb0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
bfc0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
bfd0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
bfe0: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
bff0: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
c000: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
c010: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
c020: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
c030: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
c040: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
c050: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
c060: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
c070: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
c080: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
c090: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
c0a0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
c0b0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
c0c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
c0d0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
c0e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
c0f0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
c100: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
c110: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
c120: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
c130: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
c140: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
c150: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
c160: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
c170: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
c180: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
c190: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
c1a0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
c1b0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
c1c0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
c1d0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
c1e0: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
c1f0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
c200: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
c210: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
c220: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
c230: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
c240: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
c250: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
c260: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
c270: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c280: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
c290: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c2a0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
c2b0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
c2c0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
c2d0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
c2e0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
c2f0: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
c300: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
c310: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
c320: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
c330: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
c340: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
c350: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
c360: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
c370: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
c380: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
c390: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c3a0: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
c3b0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c3c0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
c3d0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
c3e0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
c3f0: 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75   obtain the.** u
c400: 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65  nderlying native
c410: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73   file handle ass
c420: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 66  ociated with a f
c430: 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69  ile handle.  Thi
c440: 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f  s file.** contro
c450: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
c460: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70   argument as a p
c470: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69  ointer to a nati
c480: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
c490: 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65  nd.** writes the
c4a0: 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65   resulting value
c4b0: 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c   there..**.** <l
c4c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c4d0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c4e0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c4f0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c500: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
c510: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
c520: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
c530: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
c540: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
c550: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
c560: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
c570: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
c580: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
c590: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
c5a0: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
c5b0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
c5c0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
c5d0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
c5e0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
c5f0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
c600: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
c610: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c620: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
c630: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c640: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
c650: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
c660: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
c670: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
c680: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
c690: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
c6a0: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
c6b0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
c6c0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
c6d0: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
c6e0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
c6f0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
c700: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
c710: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
c720: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
c730: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
c740: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
c750: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
c760: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
c770: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
c780: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
c790: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c7a0: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
c7b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
c7c0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
c7d0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
c7e0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
c7f0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
c800: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c810: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
c820: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
c830: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c840: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
c850: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c860: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
c870: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
c880: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
c890: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
c8a0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
c8b0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
c8c0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
c8d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
c8e0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
c8f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
c900: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
c910: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
c920: 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c  ].** If the [SQL
c930: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c940: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c950: 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53 51 4c  code returns SQL
c960: 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20  ITE_OK, then.** 
c970: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
c980: 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20 69 6e  tor is placed in
c990: 20 22 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f   "batch write mo
c9a0: 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20 6d 65  de", which.** me
c9b0: 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ans all subseque
c9c0: 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  nt write operati
c9d0: 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65 66 65  ons will be defe
c9e0: 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a  rred and done.**
c9f0: 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74 20 74   atomically at t
ca00: 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54 45 5f  he next [SQLITE_
ca10: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
ca20: 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53 79 73  MIC_WRITE].  Sys
ca30: 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  tems.** that do 
ca40: 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61 74 63  not support batc
ca50: 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65 73 20  h atomic writes 
ca60: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
ca70: 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20  TE_NOTFOUND..** 
ca80: 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75 63  ^Following a suc
ca90: 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45 5f 46  cessful SQLITE_F
caa0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
cab0: 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72 69 6f  C_WRITE and prio
cac0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c 6f 73  r to.** the clos
cad0: 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ing [SQLITE_FCNT
cae0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
caf0: 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51  WRITE] or.** [SQ
cb00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
cb10: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
cb20: 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6d  ], SQLite will m
cb30: 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 69 6e  ake.** no VFS in
cb40: 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20 6f 6e  terface calls on
cb50: 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c 69 74   the same [sqlit
cb60: 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20 64 65  e3_file] file de
cb70: 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78 63 65  scriptor.** exce
cb80: 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74 6f 20  pt for calls to 
cb90: 74 68 65 20 78 57 72 69 74 65 20 6d 65 74 68 6f  the xWrite metho
cba0: 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c 65 43  d and the xFileC
cbb0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
cbc0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 46 43   with [SQLITE_FC
cbd0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a  NTL_SIZE_HINT]..
cbe0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
cbf0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
cc00: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
cc10: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
cc20: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
cc30: 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  C_WRITE] opcode 
cc40: 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65  causes all write
cc50: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73  .** operations s
cc60: 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75  ince the previou
cc70: 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  s successful cal
cc80: 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  l to .** [SQLITE
cc90: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cca0: 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65  MIC_WRITE] to be
ccb0: 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f 6d 69   performed atomi
ccc0: 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 20 66  cally..** This f
ccd0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
cce0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
ccf0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
cd00: 68 65 20 77 72 69 74 65 73 20 77 65 72 65 0a 2a  he writes were.*
cd10: 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65 64 20  * all performed 
cd20: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64  successfully and
cd30: 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d 6d 69   have been commi
cd40: 74 74 65 64 20 74 6f 20 70 65 72 73 69 73 74 65  tted to persiste
cd50: 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e  nt storage..** ^
cd60: 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
cd70: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
cd80: 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c 20 74  is successful, t
cd90: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
cda0: 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20 66 69   takes.** the fi
cdb0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75  le descriptor ou
cdc0: 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65  t of batch write
cdd0: 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20 61 6c   mode so that al
cde0: 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
cdf0: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
ce00: 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74   are independent
ce10: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
ce20: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53  l never invoke S
ce30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
ce40: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  IT_ATOMIC_WRITE 
ce50: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69  without.** a pri
ce60: 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
ce70: 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43  ll to [SQLITE_FC
ce80: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
ce90: 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  _WRITE]..**.** <
cea0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ceb0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
cec0: 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65  C_WRITE]].** The
ced0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
cee0: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
cef0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75  RITE] opcode cau
cf00: 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a  ses all write.**
cf10: 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63   operations sinc
cf20: 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  e the previous s
cf30: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
cf40: 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  o .** [SQLITE_FC
cf50: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
cf60: 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 72 6f  _WRITE] to be ro
cf70: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54  lled back..** ^T
cf80: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
cf90: 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c 65 20   takes the file 
cfa0: 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f  descriptor out o
cfb0: 66 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f  f batch write mo
cfc0: 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20 61 6c  de.** so that al
cfd0: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69  l subsequent wri
cfe0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
cff0: 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a  e independent..*
d000: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
d010: 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49  ever invoke SQLI
d020: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
d030: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 77  K_ATOMIC_WRITE w
d040: 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f  ithout.** a prio
d050: 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
d060: 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  l to [SQLITE_FCN
d070: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
d080: 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  WRITE]..**.** <l
d090: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d0a0: 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d 5d 0a  _LOCK_TIMEOUT]].
d0b0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d0c0: 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55  CNTL_LOCK_TIMEOU
d0d0: 54 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  T] opcode causes
d0e0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6f 62 74   attempts to obt
d0f0: 61 69 6e 0a 2a 2a 20 61 20 66 69 6c 65 20 6c 6f  ain.** a file lo
d100: 63 6b 20 75 73 69 6e 67 20 74 68 65 20 78 4c 6f  ck using the xLo
d110: 63 6b 20 6f 72 20 78 53 68 6d 4c 6f 63 6b 20 6d  ck or xShmLock m
d120: 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 56 46  ethods of the VF
d130: 53 20 74 6f 20 77 61 69 74 0a 2a 2a 20 66 6f 72  S to wait.** for
d140: 20 75 70 20 74 6f 20 4d 20 6d 69 6c 6c 69 73 65   up to M millise
d150: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 66 61 69  conds before fai
d160: 6c 69 6e 67 2c 20 77 68 65 72 65 20 4d 20 69 73  ling, where M is
d170: 20 74 68 65 20 73 69 6e 67 6c 65 20 0a 2a 2a 20   the single .** 
d180: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
d190: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
d1a0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
d1b0: 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f  CNTL_DATA_VERSIO
d1c0: 4e 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  N]].** The [SQLI
d1d0: 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45  TE_FCNTL_DATA_VE
d1e0: 52 53 49 4f 4e 5d 20 6f 70 63 6f 64 65 20 69 73  RSION] opcode is
d1f0: 20 75 73 65 64 20 74 6f 20 64 65 74 65 63 74 20   used to detect 
d200: 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 61 20  changes to.** a 
d210: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 20  database file.  
d220: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
d230: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 33  a pointer to a 3
d240: 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
d250: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 65 20 22  nteger..** The "
d260: 64 61 74 61 20 76 65 72 73 69 6f 6e 22 20 66 6f  data version" fo
d270: 72 20 74 68 65 20 70 61 67 65 72 20 69 73 20 77  r the pager is w
d280: 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
d290: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 0a 2a 2a  pointer.  The.**
d2a0: 20 22 64 61 74 61 20 76 65 72 73 69 6f 6e 22 20   "data version" 
d2b0: 63 68 61 6e 67 65 73 20 77 68 65 6e 65 76 65 72  changes whenever
d2c0: 20 61 6e 79 20 63 68 61 6e 67 65 20 6f 63 63 75   any change occu
d2d0: 72 73 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  rs to the corres
d2e0: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 64 61 74 61 62  ponding.** datab
d2f0: 61 73 65 20 66 69 6c 65 2c 20 65 69 74 68 65 72  ase file, either
d300: 20 74 68 72 6f 75 67 68 20 53 51 4c 20 73 74 61   through SQL sta
d310: 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73  tements on the s
d320: 61 6d 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ame database.** 
d330: 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 72 20 74 68  connection or th
d340: 72 6f 75 67 68 20 74 72 61 6e 73 61 63 74 69 6f  rough transactio
d350: 6e 73 20 63 6f 6d 6d 69 74 74 65 64 20 62 79 20  ns committed by 
d360: 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
d370: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  e.** connections
d380: 20 70 6f 73 73 69 62 6c 79 20 69 6e 20 6f 74 68   possibly in oth
d390: 65 72 20 70 72 6f 63 65 73 73 65 73 2e 20 54 68  er processes. Th
d3a0: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
d3b0: 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 69  _changes()].** i
d3c0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
d3d0: 75 73 65 64 20 74 6f 20 66 69 6e 64 20 69 66 20  used to find if 
d3e0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 6f 6e 20  any database on 
d3f0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  the connection h
d400: 61 73 20 63 68 61 6e 67 65 64 2c 0a 2a 2a 20 62  as changed,.** b
d410: 75 74 20 74 68 61 74 20 69 6e 74 65 72 66 61 63  ut that interfac
d420: 65 20 72 65 73 70 6f 6e 64 73 20 74 6f 20 63 68  e responds to ch
d430: 61 6e 67 65 73 20 6f 6e 20 54 45 4d 50 20 61 73  anges on TEMP as
d440: 20 77 65 6c 6c 20 61 73 20 4d 41 49 4e 20 61 6e   well as MAIN an
d450: 64 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 70 72  d does.** not pr
d460: 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73  ovide a mechanis
d470: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d480: 67 65 73 20 74 6f 20 4d 41 49 4e 20 6f 6e 6c 79  ges to MAIN only
d490: 2e 20 20 41 6c 73 6f 2c 20 74 68 65 0a 2a 2a 20  .  Also, the.** 
d4a0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
d4b0: 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
d4c0: 61 63 65 20 72 65 73 70 6f 6e 64 73 20 74 6f 20  ace responds to 
d4d0: 69 6e 74 65 72 6e 61 6c 20 63 68 61 6e 67 65 73  internal changes
d4e0: 20 6f 6e 6c 79 20 61 6e 64 0a 2a 2a 20 6f 6d 69   only and.** omi
d4f0: 74 73 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ts changes made 
d500: 62 79 20 6f 74 68 65 72 20 64 61 74 61 62 61 73  by other databas
d510: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 20 20  e connections.  
d520: 54 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 64  The.** [PRAGMA d
d530: 61 74 61 5f 76 65 72 73 69 6f 6e 5d 20 63 6f 6d  ata_version] com
d540: 6d 61 6e 64 20 70 72 6f 76 69 64 65 20 61 20 6d  mand provide a m
d550: 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 74 65  echanism to dete
d560: 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
d570: 20 61 20 73 69 6e 67 6c 65 20 61 74 74 61 63 68   a single attach
d580: 65 64 20 64 61 74 61 62 61 73 65 20 74 68 61 74  ed database that
d590: 20 6f 63 63 75 72 20 64 75 65 20 74 6f 20 6f 74   occur due to ot
d5a0: 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  her database con
d5b0: 6e 65 63 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74  nections,.** but
d5c0: 20 6f 6d 69 74 73 20 63 68 61 6e 67 65 73 20 69   omits changes i
d5d0: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
d5e0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
d5f0: 63 74 69 6f 6e 20 6f 6e 20 77 68 69 63 68 20 69  ction on which i
d600: 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  t is.** called. 
d610: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
d620: 6f 6c 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 6d  ol is the only m
d630: 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 74 65  echanism to dete
d640: 63 74 20 63 68 61 6e 67 65 73 20 74 68 61 74 0a  ct changes that.
d650: 2a 2a 20 68 61 70 70 65 6e 20 65 69 74 68 65 72  ** happen either
d660: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 65   internally or e
d670: 78 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 74 68  xternally and th
d680: 61 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  at are associate
d690: 64 20 77 69 74 68 0a 2a 2a 20 61 20 70 61 72 74  d with.** a part
d6a0: 69 63 75 6c 61 72 20 61 74 74 61 63 68 65 64 20  icular attached 
d6b0: 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 3c 2f 75  database..** </u
d6c0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
d6d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
d6e0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
d6f0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
d700: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
d710: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
d720: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
d730: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
d740: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
d750: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
d760: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
d770: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
d780: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
d790: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
d7a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
d7b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d7c0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
d7d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
d7e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d7f0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
d800: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
d810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d820: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
d830: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
d840: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d850: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
d860: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
d870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d880: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
d890: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
d8a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d8b0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
d8c0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
d8d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d8e0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
d8f0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
d900: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
d910: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
d920: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
d930: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
d940: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
d950: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
d960: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
d970: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
d980: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
d990: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
d9a0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
d9b0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
d9c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
d9d0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
d9e0: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
d9f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
da00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
da10: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
da20: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
da30: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
da40: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
da50: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
da60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
da70: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
da80: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
da90: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
daa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dab0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
dac0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
dad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dae0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20  CNTL_WAL_BLOCK  
daf0: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23              24.#
db00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
db10: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20  NTL_ZIPVFS      
db20: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64             25.#d
db30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
db40: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20  TL_RBU          
db50: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65            26.#de
db60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
db70: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20  L_VFS_POINTER   
db80: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66           27.#def
db90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
dba0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
dbb0: 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69          28.#defi
dbc0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dbd0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
dbe0: 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e         29.#defin
dbf0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
dc00: 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20  DB              
dc10: 20 20 20 20 20 20 33 30 0a 23 64 65 66 69 6e 65        30.#define
dc20: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45   SQLITE_FCNTL_BE
dc30: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
dc40: 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e 65 20       31.#define 
dc50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
dc60: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
dc70: 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
dc80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
dc90: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
dca0: 45 20 20 33 33 0a 23 64 65 66 69 6e 65 20 53 51  E  33.#define SQ
dcb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f  LITE_FCNTL_LOCK_
dcc0: 54 49 4d 45 4f 55 54 20 20 20 20 20 20 20 20 20  TIMEOUT         
dcd0: 20 20 33 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    34.#define SQL
dce0: 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56  ITE_FCNTL_DATA_V
dcf0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ERSION          
dd00: 20 33 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   35.#define SQLI
dd10: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49  TE_FCNTL_SIZE_LI
dd20: 4d 49 54 20 20 20 20 20 20 20 20 20 20 20 20 20  MIT             
dd30: 33 36 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65  36../* deprecate
dd40: 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69  d names */.#defi
dd50: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
dd60: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
dd70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
dd80: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
dd90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
dda0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ddb0: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
ddc0: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
ddd0: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
dde0: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
ddf0: 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54             SQLIT
de00: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
de10: 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  NO.../*.** CAPI3
de20: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
de30: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
de40: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
de50: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
de60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
de70: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
de80: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
de90: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
dea0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
deb0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
dec0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
ded0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
dee0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
def0: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
df00: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
df10: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
df20: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
df30: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
df40: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
df50: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
df60: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
df70: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
df80: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
df90: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
dfa0: 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61   CAPI3REF: Loada
dfb0: 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68  ble Extension Th
dfc0: 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e  unk.**.** A poin
dfd0: 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75  ter to the opaqu
dfe0: 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  e sqlite3_api_ro
dff0: 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72 65  utines structure
e000: 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a   is passed as.**
e010: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
e020: 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f  eter to entry po
e030: 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c  ints of [loadabl
e040: 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20  e extensions].  
e050: 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  This.** structur
e060: 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64 65  e must be typede
e070: 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  fed in order to 
e080: 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70  work around comp
e090: 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a  iler warnings.**
e0a0: 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72   on some platfor
e0b0: 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ms..*/.typedef s
e0c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70  truct sqlite3_ap
e0d0: 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74  i_routines sqlit
e0e0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b  e3_api_routines;
e0f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e100: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
e110: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
e120: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
e130: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e140: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
e150: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
e160: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
e170: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
e180: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
e190: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
e1a0: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
e1b0: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
e1c0: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
e1d0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
e1e0: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
e1f0: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
e200: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
e210: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
e220: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 56 46 53 20 69  .**.** The VFS i
e230: 6e 74 65 72 66 61 63 65 20 69 73 20 73 6f 6d 65  nterface is some
e240: 74 69 6d 65 73 20 65 78 74 65 6e 64 65 64 20 62  times extended b
e250: 79 20 61 64 64 69 6e 67 20 6e 65 77 20 6d 65 74  y adding new met
e260: 68 6f 64 73 20 6f 6e 74 6f 0a 2a 2a 20 74 68 65  hods onto.** the
e270: 20 65 6e 64 2e 20 20 45 61 63 68 20 74 69 6d 65   end.  Each time
e280: 20 73 75 63 68 20 61 6e 20 65 78 74 65 6e 73 69   such an extensi
e290: 6f 6e 20 6f 63 63 75 72 73 2c 20 74 68 65 20 69  on occurs, the i
e2a0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 0a 2a 2a  Version field.**
e2b0: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e   is incremented.
e2c0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20 76    The iVersion v
e2d0: 61 6c 75 65 20 73 74 61 72 74 65 64 20 6f 75 74  alue started out
e2e0: 20 61 73 20 31 20 69 6e 0a 2a 2a 20 53 51 4c 69   as 1 in.** SQLi
e2f0: 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e  te [version 3.5.
e300: 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e  0] on [dateof:3.
e310: 35 2e 30 5d 2c 20 74 68 65 6e 20 69 6e 63 72 65  5.0], then incre
e320: 61 73 65 64 20 74 6f 20 32 0a 2a 2a 20 77 69 74  ased to 2.** wit
e330: 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  h SQLite [versio
e340: 6e 20 33 2e 37 2e 30 5d 20 6f 6e 20 5b 64 61 74  n 3.7.0] on [dat
e350: 65 6f 66 3a 33 2e 37 2e 30 5d 2c 20 61 6e 64 20  eof:3.7.0], and 
e360: 74 68 65 6e 20 69 6e 63 72 65 61 73 65 64 0a 2a  then increased.*
e370: 2a 20 74 6f 20 33 20 77 69 74 68 20 53 51 4c 69  * to 3 with SQLi
e380: 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e  te [version 3.7.
e390: 36 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e  6] on [dateof:3.
e3a0: 37 2e 36 5d 2e 20 20 41 64 64 69 74 69 6f 6e 61  7.6].  Additiona
e3b0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 6d 61 79 20  l fields.** may 
e3c0: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
e3d0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
e3e0: 62 6a 65 63 74 20 61 6e 64 20 74 68 65 20 69 56  bject and the iV
e3f0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 0a 2a 2a 20  ersion value.** 
e400: 6d 61 79 20 69 6e 63 72 65 61 73 65 20 61 67 61  may increase aga
e410: 69 6e 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  in in future ver
e420: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
e430: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
e440: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
e450: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
e460: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
e470: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 69 74 69   in the transiti
e480: 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 53 51 4c 69 74  on from.** SQLit
e490: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  e [version 3.5.9
e4a0: 5d 20 74 6f 20 5b 76 65 72 73 69 6f 6e 20 33 2e  ] to [version 3.
e4b0: 36 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a  6.0] on [dateof:
e4c0: 33 2e 36 2e 30 5d 0a 2a 2a 20 61 6e 64 20 79 65  3.6.0].** and ye
e4d0: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
e4e0: 69 65 6c 64 20 77 61 73 20 6e 6f 74 20 6d 6f 64  ield was not mod
e4f0: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
e500: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
e510: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
e520: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
e530: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
e540: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
e550: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
e560: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
e570: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
e580: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
e590: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
e5a0: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
e5b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
e5c0: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
e5d0: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
e5e0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
e5f0: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
e600: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
e610: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
e620: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
e630: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
e640: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
e650: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
e660: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
e670: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
e680: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
e690: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
e6a0: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
e6b0: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
e6c0: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
e6d0: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
e6e0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
e6f0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
e700: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
e710: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
e720: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
e730: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
e740: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
e750: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
e760: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
e770: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
e780: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
e790: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
e7a0: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
e7b0: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
e7c0: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
e7d0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
e7e0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
e7f0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
e800: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
e810: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
e820: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
e830: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
e840: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
e850: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
e860: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
e870: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
e880: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
e890: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
e8a0: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  ules..**.** [[sq
e8b0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
e8c0: 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ].** ^SQLite gua
e8d0: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
e8e0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
e8f0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
e900: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
e910: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
e920: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
e930: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
e940: 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74  me() with an opt
e950: 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64  ional suffix add
e960: 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66  ed..** ^If a suf
e970: 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20  fix is added to 
e980: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
e990: 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c  rameter, it will
e9a0: 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  .** consist of a
e9b0: 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72   single "-" char
e9c0: 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62  acter followed b
e9d0: 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a  y no more than.*
e9e0: 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69  * 11 alphanumeri
e9f0: 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61  c and/or "-" cha
ea00: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c  racters..** ^SQL
ea10: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
ea20: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
ea30: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
ea40: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
ea50: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
ea60: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
ea70: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
ea80: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
ea90: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
eaa0: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
eab0: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
eac0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
ead0: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
eae0: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
eaf0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
eb00: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
eb10: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
eb20: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
eb30: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
eb40: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
eb50: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
eb60: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
eb70: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
eb80: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
eb90: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
eba0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
ebb0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
ebc0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
ebd0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
ebe0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
ebf0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
ec00: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
ec10: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
ec20: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
ec30: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
ec40: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
ec50: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
ec60: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
ec70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
ec80: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
ec90: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
eca0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
ecb0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
ecc0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
ecd0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
ece0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
ecf0: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
ed00: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
ed10: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
ed20: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
ed30: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
ed40: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
ed50: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
ed60: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
ed70: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
ed80: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
ed90: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
eda0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
edb0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
edc0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
edd0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
ede0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
edf0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
ee00: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
ee10: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
ee20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
ee30: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
ee40: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
ee50: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
ee60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
ee70: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
ee80: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
ee90: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
eea0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
eeb0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
eec0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
eed0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
eee0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
eef0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
ef00: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
ef10: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
ef20: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
ef30: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
ef40: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
ef50: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
ef60: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
ef70: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
ef80: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
ef90: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
efa0: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
efb0: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
efc0: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
efd0: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
efe0: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
eff0: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
f000: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
f010: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
f020: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
f030: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
f040: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
f050: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
f060: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
f070: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
f080: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
f090: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
f0a0: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
f0b0: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
f0c0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
f0d0: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
f0e0: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
f0f0: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
f100: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
f110: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
f120: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
f130: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
f140: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
f150: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
f160: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
f170: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
f180: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
f190: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
f1a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
f1b0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
f1c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
f1d0: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
f1e0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
f1f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
f200: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
f210: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
f220: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
f230: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
f240: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
f250: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
f260: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
f270: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
f280: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
f290: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
f2a0: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
f2b0: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
f2c0: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
f2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f2e0: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
f2f0: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
f300: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
f310: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
f320: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
f330: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
f340: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
f350: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
f360: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
f370: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
f380: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
f390: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
f3a0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
f3b0: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
f3c0: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
f3d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
f3e0: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
f3f0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
f400: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
f410: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
f420: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
f430: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
f440: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
f450: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
f460: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
f470: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
f480: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
f490: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
f4a0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
f4b0: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
f4c0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
f4d0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
f4e0: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
f4f0: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
f500: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
f510: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
f520: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
f530: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
f540: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
f550: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
f560: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
f570: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
f580: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
f590: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
f5a0: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
f5b0: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
f5c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
f5d0: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
f5e0: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
f5f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
f600: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
f610: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
f620: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
f630: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
f640: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
f650: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
f660: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
f670: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
f680: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
f690: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
f6a0: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
f6b0: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
f6c0: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
f6d0: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  n call..**.** [[
f6e0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63  sqlite3_vfs.xAcc
f6f0: 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c  ess]].** ^The fl
f700: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
f710: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
f720: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
f730: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
f740: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
f750: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
f760: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
f770: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
f780: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
f790: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
f7a0: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
f7b0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
f7c0: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
f7d0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
f7e0: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
f7f0: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
f800: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
f810: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
f820: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
f830: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
f840: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
f850: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
f860: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
f870: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
f880: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
f890: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
f8a0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
f8b0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
f8c0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
f8d0: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
f8e0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
f8f0: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
f900: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
f910: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
f920: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
f930: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
f940: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
f950: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
f960: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
f970: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
f980: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
f990: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
f9a0: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
f9b0: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
f9c0: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
f9d0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
f9e0: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
f9f0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
fa00: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
fa10: 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
fa20: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
fa30: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
fa40: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
fa50: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
fa60: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
fa70: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
fa80: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
fa90: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
faa0: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
fab0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
fac0: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
fad0: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
fae0: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
faf0: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
fb00: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
fb10: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
fb20: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
fb30: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
fb40: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
fb50: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
fb60: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
fb70: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
fb80: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
fb90: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
fba0: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
fbb0: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
fbc0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
fbd0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
fbe0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
fbf0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
fc00: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
fc10: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
fc20: 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
fc30: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
fc40: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
fc50: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
fc60: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
fc70: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
fc80: 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30  plied by 8640000
fc90: 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  0 (the number of
fca0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e   milliseconds in
fcb0: 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64   .** a 24-hour d
fcc0: 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74  ay).  .** ^SQLit
fcd0: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78  e will use the x
fce0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
fcf0: 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74  () method to get
fd00: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
fd10: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66  date and time if
fd20: 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20   that method is 
fd30: 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56  available (if iV
fd40: 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a  ersion is 2 or .
fd50: 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74  ** greater and t
fd60: 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
fd70: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29  ter is not NULL)
fd80: 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62   and will fall b
fd90: 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65  ack.** to xCurre
fda0: 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72  ntTime() if xCur
fdb0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
fdc0: 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
fdd0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53  **.** ^The xSetS
fde0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65  ystemCall(), xGe
fdf0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61  tSystemCall(), a
fe00: 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61  nd xNestSystemCa
fe10: 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  ll() interfaces.
fe20: 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20  ** are not used 
fe30: 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  by the SQLite co
fe40: 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f  re.  These optio
fe50: 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  nal interfaces a
fe60: 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62  re provided.** b
fe70: 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20  y some VFSes to 
fe80: 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69  facilitate testi
fe90: 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f  ng of the VFS co
fea0: 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e  de. By overridin
feb0: 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c  g .** system cal
fec0: 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e  ls with function
fed0: 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74  s under its cont
fee0: 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67  rol, a test prog
fef0: 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c  ram can.** simul
ff00: 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65  ate faults and e
ff10: 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20  rror conditions 
ff20: 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72  that would other
ff30: 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c  wise be difficul
ff40: 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62  t.** or impossib
ff50: 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54  le to induce.  T
ff60: 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d  he set of system
ff70: 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20   calls that can 
ff80: 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a  be overridden.**
ff90: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
ffa0: 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c   VFS to another,
ffb0: 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65   and from one ve
ffc0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d  rsion of the sam
ffd0: 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20  e VFS to the.** 
ffe0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
fff0: 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65  ons that use the
10000 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75  se interfaces mu
10010 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66  st be prepared f
10020 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c  or any.** or all
10030 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66   of these interf
10040 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20  aces to be NULL 
10050 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68  or for their beh
10060 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a  avior to change.
10070 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65  ** from one rele
10080 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ase to the next.
10090 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d    Applications m
100a0 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  ust not attempt 
100b0 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79  to access.** any
100c0 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64   of these method
100d0 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f  s if the iVersio
100e0 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20  n of the VFS is 
100f0 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a  less than 3..*/.
10100 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
10110 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
10120 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20  e3_vfs;.typedef 
10130 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73  void (*sqlite3_s
10140 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64  yscall_ptr)(void
10150 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  );.struct sqlite
10160 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
10170 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
10180 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
10190 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
101a0 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a  currently 3) */.
101b0 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
101c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
101d0 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
101e0 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
101f0 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
10200 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
10210 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
10220 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
10230 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
10240 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
10250 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
10260 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
10270 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
10280 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
10290 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
102a0 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
102b0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
102c0 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
102d0 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
102e0 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
102f0 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
10300 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10310 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
10320 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
10330 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
10340 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
10350 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
10360 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
10370 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
10380 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
10390 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
103a0 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
103b0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
103c0 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
103d0 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
103e0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
103f0 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
10400 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10410 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
10420 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
10430 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
10440 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
10450 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
10460 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
10470 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
10480 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
10490 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
104a0 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
104b0 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
104c0 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
104d0 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
104e0 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
104f0 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
10500 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
10510 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
10520 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
10530 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
10540 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
10550 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
10560 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
10570 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
10580 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
10590 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
105a0 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
105b0 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
105c0 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
105d0 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
105e0 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
105f0 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
10600 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20  in version 1 of 
10610 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
10620 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e  bject.  ** defin
10630 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68  ition.  Those th
10640 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64  at follow are ad
10650 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32  ded in version 2
10660 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20   or later.  */. 
10670 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
10680 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
10690 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
106a0 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
106b0 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
106c0 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
106d0 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
106e0 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
106f0 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73  bject..  ** Thos
10700 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20  e below are for 
10710 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72  version 3 and gr
10720 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e  eater..  */.  in
10730 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61  t (*xSetSystemCa
10740 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
10750 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
10760 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73  ame, sqlite3_sys
10770 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c  call_ptr);.  sql
10780 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
10790 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c   (*xGetSystemCal
107a0 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
107b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
107c0 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61  me);.  const cha
107d0 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d  r *(*xNextSystem
107e0 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
107f0 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
10800 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a  zName);.  /*.  *
10810 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
10820 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
10830 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20  ons 1 through 3 
10840 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
10850 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
10860 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
10870 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74   appended in fut
10880 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
10890 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
108a0 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
108b0 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
108c0 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
108d0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
108e0 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
108f0 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
10900 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
10910 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
10920 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
10930 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
10940 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
10950 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10960 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
10970 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
10980 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
10990 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
109a0 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
109b0 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
109c0 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
109d0 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
109e0 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
109f0 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
10a00 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
10a10 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
10a20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
10a30 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10a40 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
10a50 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
10a60 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
10a70 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72  e named director
10a80 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  y is both readab
10a90 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a  le and writable.
10aa0 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72  ** (in other wor
10ab0 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e  ds, if files can
10ac0 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76   be added, remov
10ad0 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20  ed, and renamed 
10ae0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69  within.** the di
10af0 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65  rectory)..** The
10b00 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10b10 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e  EADWRITE constan
10b20 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75  t is currently u
10b30 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a  sed only by the.
10b40 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  ** [temp_store_d
10b50 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
10b60 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f  , though this co
10b70 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20  uld change in a 
10b80 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
10b90 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  e of SQLite..** 
10ba0 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
10bb0 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
10bc0 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
10bd0 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
10be0 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
10bf0 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  le.  The SQLITE_
10c00 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73  ACCESS_READ cons
10c10 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65  tant is.** curre
10c20 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f  ntly unused, tho
10c30 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20  ugh it might be 
10c40 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65  used in a future
10c50 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
10c60 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
10c70 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10c80 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
10c90 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
10ca0 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20  S_READWRITE 1   
10cb0 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d  /* Used by PRAGM
10cc0 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72  A temp_store_dir
10cd0 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e  ectory */.#defin
10ce0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10cf0 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a  READ      2   /*
10d00 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a   Unused */../*.*
10d10 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
10d20 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f  s for the xShmLo
10d30 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ck VFS method.**
10d40 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
10d50 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  r constants defi
10d60 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  ne the various l
10d70 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e  ocking operation
10d80 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20  s.** allowed by 
10d90 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  the xShmLock met
10da0 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  hod of [sqlite3_
10db0 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68  io_methods].  Th
10dc0 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  e.** following a
10dd0 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61  re the only lega
10de0 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f  l combinations o
10df0 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a  f flags to the.*
10e00 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  * xShmLock metho
10e10 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
10e20 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
10e30 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
10e40 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
10e50 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
10e60 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
10e70 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c  _EXCLUSIVE.** <l
10e80 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
10e90 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
10ea0 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
10eb0 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
10ec0 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
10ed0 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
10ee0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  /ul>.**.** When 
10ef0 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73  unlocking, the s
10f00 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58  ame SHARED or EX
10f10 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73  CLUSIVE flag mus
10f20 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73  t be supplied as
10f30 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e  .** was given on
10f40 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
10f50 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a  ng lock.  .**.**
10f60 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
10f70 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74  thod can transit
10f80 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  ion between unlo
10f90 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20  cked and SHARED 
10fa0 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e  or.** between un
10fb0 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55  locked and EXCLU
10fc0 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74  SIVE.  It cannot
10fd0 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
10fe0 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e  een SHARED.** an
10ff0 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a  d EXCLUSIVE..*/.
11000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11010 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
11020 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
11030 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20  _SHM_LOCK       
11040 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
11050 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20  TE_SHM_SHARED   
11060 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
11070 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
11080 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43  VE    8../*.** C
11090 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d  API3REF: Maximum
110a0 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a   xShmLock index.
110b0 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
110c0 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71  ck method on [sq
110d0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
110e0 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73  ] may use values
110f0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
11100 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75  d this upper bou
11110 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65  nd as its "offse
11120 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  t" argument..** 
11130 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
11140 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d  will never attem
11150 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72  pt to acquire or
11160 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f   release a.** lo
11170 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  ck outside of th
11180 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66  is range.*/.#def
11190 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e  ine SQLITE_SHM_N
111a0 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a  LOCK        8...
111b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
111c0 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
111d0 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
111e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
111f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
11200 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
11210 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
11220 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73  library.  ^The s
11230 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11240 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
11250 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
11260 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
11270 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
11280 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11290 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ()..** These rou
112a0 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e  tines are design
112b0 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f  ed to aid in pro
112c0 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
112d0 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64  ion and.** shutd
112e0 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20  own on embedded 
112f0 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74  systems.  Workst
11300 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f  ation applicatio
11310 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69  ns using.** SQLi
11320 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e  te normally do n
11330 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b  ot need to invok
11340 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
11350 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
11360 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to 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 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
11390 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
113a0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
113b0 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
113c0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
113d0 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
113e0 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
113f0 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
11400 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
11410 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
11420 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
11430 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
11440 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
11450 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
11460 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63   ^(Only an effec
11470 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
11480 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11490 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
114a0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
114b0 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
114c0 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
114d0 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  o-ops.)^.**.** A
114e0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
114f0 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
11500 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
11510 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
11520 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
11530 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11540 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
11550 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
11560 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79  alize().  ^(Only
11570 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65  .** an effective
11580 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11590 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73  _shutdown() does
115a0 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a   any deinitializ
115b0 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74  ation..** All ot
115c0 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20  her valid calls 
115d0 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
115e0 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
115f0 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
11600 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
11610 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
11620 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
11630 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
11640 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
11650 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
11660 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
11670 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
11680 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
11690 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
116a0 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
116b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
116c0 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
116d0 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
116e0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
116f0 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
11700 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
11710 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
11720 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11730 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
11740 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e   other things, ^
11750 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11760 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ze() will invoke
11770 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
11780 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
11790 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74  y, ^sqlite3_shut
117a0 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69  down().** will i
117b0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
117c0 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _end()..**.** ^T
117d0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
117e0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
117f0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
11800 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
11810 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20  ** ^If for some 
11820 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
11830 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
11840 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
11850 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
11860 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
11870 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
11880 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
11890 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
118a0 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
118b0 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
118c0 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
118d0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
118e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
118f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
11900 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
11910 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
11920 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
11930 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
11940 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
11950 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
11960 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
11970 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
11980 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
11990 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
119a0 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
119b0 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
119c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
119d0 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
119e0 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
119f0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
11a00 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
11a10 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
11a20 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
11a30 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
11a40 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
11a50 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76  already.  ^Howev
11a60 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
11a70 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
11a80 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
11a90 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
11aa0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11ab0 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
11ac0 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
11ad0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11ae0 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
11af0 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
11b00 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
11b10 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11b20 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
11b30 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
11b40 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
11b50 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
11b60 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
11b70 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
11b80 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
11b90 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
11ba0 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
11bb0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
11bc0 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
11bd0 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
11be0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
11bf0 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
11c00 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
11c10 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
11c20 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
11c30 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
11c40 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
11c50 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
11c60 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
11c70 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
11c80 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
11c90 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
11ca0 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
11cb0 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
11cc0 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
11cd0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
11ce0 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
11cf0 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
11d00 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
11d10 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
11d20 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
11d30 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
11d40 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
11d50 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
11d60 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
11d70 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11d80 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
11d90 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
11da0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
11db0 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
11dc0 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
11dd0 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
11de0 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
11df0 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
11e00 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
11e10 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
11e20 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
11e30 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
11e40 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
11e50 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
11e60 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
11e70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
11e80 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
11e90 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
11ea0 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
11eb0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11ec0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
11ed0 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
11ee0 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
11ef0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
11f00 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
11f10 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11f20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
11f30 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
11f40 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
11f50 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
11f60 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
11f70 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
11f80 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
11f90 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
11fa0 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
11fb0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11fc0 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
11fd0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
11fe0 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
11ff0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
12000 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
12010 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
12020 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
12030 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
12040 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20   Unix, Windows, 
12050 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or OS/2..** When
12060 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20   [custom builds 
12070 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  | built for othe
12080 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20  r platforms].** 
12090 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49  (using the [SQLI
120a0 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63  TE_OS_OTHER=1] c
120b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
120c0 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
120d0 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
120e0 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
120f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
12100 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
12110 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
12120 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
12130 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
12140 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
12150 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
12160 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
12170 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
12180 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b  ** must return [
12190 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
121a0 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
121b0 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
121c0 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
121d0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
121e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69   int sqlite3_ini
121f0 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53  tialize(void);.S
12200 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
12210 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
12220 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
12230 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f   int sqlite3_os_
12240 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49  init(void);.SQLI
12250 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
12260 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
12270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12280 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
12290 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
122a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
122b0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
122c0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
122d0 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
122e0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
122f0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
12300 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
12310 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
12320 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
12330 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
12340 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
12350 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
12360 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
12370 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
12380 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
12390 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
123a0 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
123b0 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
123c0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
123d0 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
123e0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
123f0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
12400 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  <b>The sqlite3_c
12410 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
12420 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
12430 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61  afe. The applica
12440 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
12450 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
12460 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
12470 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
12480 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
12490 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
124a0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
124b0 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  nning.</b>.**.**
124c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
124d0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a  fig() interface.
124e0 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
124f0 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
12500 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
12510 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
12520 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
12530 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
12540 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
12550 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
12560 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
12570 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
12580 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
12590 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
125a0 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
125b0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
125c0 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
125d0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
125e0 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
125f0 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
12600 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12610 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
12620 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
12630 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
12640 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
12650 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
12660 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
12670 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
12680 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
12690 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
126a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
126b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
126c0 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
126d0 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
126e0 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
126f0 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
12700 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
12710 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
12720 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
12730 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
12740 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
12750 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12760 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
12770 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12780 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
12790 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
127a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
127b0 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
127c0 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
127d0 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
127e0 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
127f0 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
12800 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
12810 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
12820 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
12830 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
12840 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
12850 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
12860 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
12870 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
12880 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  nections.** METH
12890 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
128a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
128b0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
128c0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
128d0 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
128e0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
128f0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
12900 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
12910 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
12920 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
12930 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
12940 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
12950 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
12960 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
12970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
12980 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
12990 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
129a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
129b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
129c0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
129d0 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
129e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
129f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
12a00 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
12a10 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
12a20 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
12a30 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
12a40 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
12a50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12a60 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
12a70 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
12a80 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
12a90 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
12aa0 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
12ab0 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
12ac0 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
12ad0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
12ae0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
12af0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
12b00 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
12b10 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
12b20 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
12b30 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
12b40 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
12b50 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
12b60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12b70 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
12b80 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
12b90 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
12ba0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
12bb0 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
12bc0 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
12bd0 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
12be0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
12bf0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
12c00 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
12c10 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
12c20 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
12c30 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
12c40 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
12c50 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12c60 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
12c70 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
12c80 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12c90 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
12ca0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
12cb0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
12cc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12cd0 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  OC] or [SQLITE_C
12ce0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
12cf0 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69  .  .** By creati
12d00 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
12d10 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
12d20 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
12d30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
12d40 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
12d50 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64  IG_MALLOC]).** d
12d60 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
12d70 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ion, an applicat
12d80 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
12d90 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
12da0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
12db0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ion subsystem fo
12dc0 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
12dd0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a  for all of its.*
12de0 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  * dynamic memory
12df0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
12e00 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
12e10 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61  omes with severa
12e20 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  l [built-in memo
12e30 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a  ry allocators].*
12e40 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65  * that are perfe
12e50 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
12e60 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
12e70 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
12e80 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
12e90 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
12ea0 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
12eb0 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
12ec0 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
12ed0 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
12ee0 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
12ef0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
12f00 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
12f10 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
12f20 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
12f30 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
12f40 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
12f50 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
12f60 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
12f70 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
12f80 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
12f90 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
12fa0 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
12fb0 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
12fc0 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
12fd0 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
12fe0 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
12ff0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
13000 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63  Malloc, xRealloc
13010 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  , and xFree meth
13020 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
13030 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
13040 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
13050 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
13060 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
13070 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
13080 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
13090 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
130a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
130b0 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73  o.** xRealloc is
130c0 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20   always a value 
130d0 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72  returned by a pr
130e0 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75  ior call to xRou
130f0 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  ndup..**.** xSiz
13100 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
13110 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
13120 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
13130 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
13140 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
13150 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
13160 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
13170 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
13180 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
13190 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
131a0 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
131b0 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
131c0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
131d0 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
131e0 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
131f0 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
13200 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
13210 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13220 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
13230 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
13240 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
13250 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
13260 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
13270 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
13280 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
13290 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
132a0 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
132b0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
132c0 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
132d0 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
132e0 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
132f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13300 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
13310 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
13320 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
13330 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
13340 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
13350 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
13360 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
13370 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
13380 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
13390 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
133a0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
133b0 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
133c0 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
133d0 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
133e0 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72   allocator.  For
133f0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
13400 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
13410 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
13420 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
13430 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
13440 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
13450 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
13460 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
13470 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
13480 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
13490 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
134a0 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
134b0 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
134c0 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
134d0 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
134e0 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
134f0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
13500 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
13510 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
13520 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
13530 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
13540 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
13550 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
13560 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
13570 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
13580 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
13590 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
135a0 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
135b0 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
135c0 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
135d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
135e0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
135f0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
13600 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
13610 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
13620 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
13630 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
13640 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
13650 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
13660 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
13670 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
13680 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13690 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
136a0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
136b0 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
136c0 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
136d0 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
136e0 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
136f0 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
13700 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
13710 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
13720 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
13730 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
13740 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
13750 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
13760 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
13770 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
13780 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
13790 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
137a0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
137b0 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
137c0 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
137d0 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
137e0 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
137f0 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
13800 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
13810 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
13820 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
13830 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
13840 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
13850 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
13860 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
13870 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
13880 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
13890 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
138a0 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
138b0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
138c0 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
138d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
138e0 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
138f0 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
13900 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
13910 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
13920 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
13930 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
13940 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
13950 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
13960 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
13970 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
13980 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
13990 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
139a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
139b0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
139c0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
139d0 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
139e0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
139f0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
13a00 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
13a10 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
13a20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
13a30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13a40 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
13a50 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
13a60 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
13a70 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
13a80 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
13a90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13aa0 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
13ab0 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
13ac0 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
13ad0 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
13ae0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
13af0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
13b00 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
13b10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13b20 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
13b30 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
13b40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
13b50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
13b60 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
13b70 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
13b80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13b90 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
13ba0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
13bb0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
13bc0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
13bd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
13be0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
13bf0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
13c00 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
13c10 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
13c20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
13c30 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
13c40 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
13c50 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
13c60 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
13c70 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
13c80 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
13c90 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
13ca0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
13cb0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
13cc0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
13cd0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13ce0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
13cf0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
13d00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13d10 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
13d20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13d30 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
13d40 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13d50 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
13d60 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
13d70 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
13d80 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
13d90 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
13da0 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
13db0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
13dc0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
13dd0 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
13de0 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
13df0 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
13e00 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
13e10 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
13e20 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
13e30 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13e40 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13e50 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13e60 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13e70 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13e80 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13e90 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
13ea0 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
13eb0 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
13ec0 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
13ed0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
13ee0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
13ef0 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
13f00 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
13f10 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
13f20 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
13f30 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
13f40 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
13f50 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
13f60 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
13f70 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13f80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
13f90 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
13fa0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
13fb0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
13fc0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
13fd0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
13fe0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
13ff0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
14000 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
14010 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
14020 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
14030 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
14040 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
14050 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14060 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
14070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
14080 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
14090 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
140a0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
140b0 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
140c0 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
140d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
140e0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
140f0 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
14100 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
14110 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
14120 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
14130 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
14140 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
14150 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
14160 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
14170 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
14180 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
14190 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
141a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
141b0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
141c0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
141d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
141e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
141f0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14200 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14210 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14220 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
14230 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
14240 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
14250 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
14260 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
14270 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14280 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
14290 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
142a0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
142b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
142c0 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
142d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
142e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
142f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
14300 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
14310 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
14320 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
14330 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
14340 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
14350 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
14360 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
14370 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
14380 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
14390 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
143a0 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
143b0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
143c0 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
143d0 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
143e0 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
143f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14400 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
14410 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
14420 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
14430 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
14440 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
14450 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14460 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
14470 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
14480 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
14490 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
144a0 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
144b0 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
144c0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
144d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
144e0 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
144f0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
14500 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
14510 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
14520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14530 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
14540 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14550 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
14560 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
14570 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
14580 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14590 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
145a0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
145b0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
145c0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
145d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
145e0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
145f0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
14600 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
14610 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14620 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
14630 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
14640 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
14650 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
14660 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
14670 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
14680 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
14690 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
146a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
146b0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
146c0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
146d0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
146e0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
146f0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
14700 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14710 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14720 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
14730 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
14740 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
14750 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
14760 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
14770 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
14780 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
14790 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
147a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
147b0 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
147c0 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
147d0 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
147e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
147f0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
14800 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
14810 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
14820 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
14830 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
14840 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
14850 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
14860 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
14870 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
14880 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
14890 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
148a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
148b0 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
148c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
148d0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
148e0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
148f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
14900 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
14910 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14920 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
14930 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
14940 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
14950 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14960 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
14970 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
14980 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
14990 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
149a0 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
149b0 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
149c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
149d0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
149e0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
149f0 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
14a00 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
14a10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
14a20 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
14a30 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
14a40 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
14a50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
14a60 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
14a70 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
14a80 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
14a90 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14aa0 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f  TE_CONFIG_SMALL_
14ab0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
14ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
14ad0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
14ae0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
14af0 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41  _CONFIG_SMALL_MA
14b00 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
14b10 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
14b20 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69 6e 74  t of.** type int
14b30 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
14b40 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63   a boolean, whic
14b50 68 20 69 66 20 74 72 75 65 20 70 72 6f 76 69 64  h if true provid
14b60 65 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a 2a 20  es a hint to.** 
14b70 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 73  SQLite that it s
14b80 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61 72 67  hould avoid larg
14b90 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14ba0 69 6f 6e 73 20 69 66 20 70 6f 73 73 69 62 6c 65  ions if possible
14bb0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  ..** SQLite will
14bc0 20 72 75 6e 20 66 61 73 74 65 72 20 69 66 20 69   run faster if i
14bd0 74 20 69 73 20 66 72 65 65 20 74 6f 20 6d 61 6b  t is free to mak
14be0 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61  e large memory a
14bf0 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a 20 62  llocations,.** b
14c00 75 74 20 73 6f 6d 65 20 61 70 70 6c 69 63 61 74  ut some applicat
14c10 69 6f 6e 20 6d 69 67 68 74 20 70 72 65 66 65 72  ion might prefer
14c20 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72 20 69   to run slower i
14c30 6e 20 65 78 63 68 61 6e 67 65 20 66 6f 72 0a 2a  n exchange for.*
14c40 2a 20 67 75 61 72 61 6e 74 65 65 73 20 61 62 6f  * guarantees abo
14c50 75 74 20 6d 65 6d 6f 72 79 20 66 72 61 67 6d 65  ut memory fragme
14c60 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 61 72 65  ntation that are
14c70 20 70 6f 73 73 69 62 6c 65 20 69 66 20 6c 61 72   possible if lar
14c80 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ge.** allocation
14c90 73 20 61 72 65 20 61 76 6f 69 64 65 64 2e 20 20  s are avoided.  
14ca0 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 72  This hint is nor
14cb0 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20 3c 2f  mally off..** </
14cc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14cd0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
14ce0 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
14cf0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14d00 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
14d10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14d20 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69  G_MEMSTATUS opti
14d30 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
14d40 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
14d50 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72   int,.** interpr
14d60 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
14d70 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
14d80 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
14d90 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a   collection of.*
14da0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
14db0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20  ion statistics. 
14dc0 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
14dd0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
14de0 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  ics are.** disab
14df0 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  led, the followi
14e00 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
14e10 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
14e20 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
14e30 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
14e40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
14e50 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
14e60 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
14e70 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
14e80 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
14e90 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
14ea0 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
14eb0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
14ec0 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  s64()].**   </ul
14ed0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
14ee0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14ef0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
14f00 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
14f10 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
14f20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
14f30 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
14f40 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
14f50 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
14f60 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
14f70 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
14f80 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
14f90 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14fa0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14fb0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
14fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14fd0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
14fe0 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
14ff0 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
15000 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
15010 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  used..** </dd>.*
15020 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15030 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
15040 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15050 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
15060 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
15070 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15080 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
15090 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79  ecifies a memory
150a0 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51   pool.** that SQ
150b0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
150c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
150d0 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
150e0 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a  e default page.*
150f0 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
15100 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
15110 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
15120 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f  option is a no-o
15130 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  p if an applicat
15140 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
15150 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
15160 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
15170 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
15180 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15190 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  E2]..** ^There a
151a0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
151b0 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
151c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41  FIG_PAGECACHE: A
151d0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38   pointer to.** 8
151e0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65  -byte aligned me
151f0 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65  mory (pMem), the
15200 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
15210 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73  ge cache line (s
15220 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e  z),.** and the n
15230 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c  umber of cache l
15240 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ines (N)..** The
15250 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
15260 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
15270 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
15280 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
15290 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
152a0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
152b0 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
152c0 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
152d0 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
152e0 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
152f0 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
15300 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
15310 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
15320 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
15330 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43   using [SQLITE_C
15340 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
15350 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68  SZ]..** ^It is h
15360 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
15370 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
15380 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68  emory,.** for th
15390 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74  e sz parameter t
153a0 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  o be larger than
153b0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65   necessary.  The
153c0 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e   pMem.** argumen
153d0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
153e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
153f0 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
15400 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
15410 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  gned block of me
15420 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
15430 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68   sz*N bytes, oth
15440 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71  erwise.** subseq
15450 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
15460 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
15470 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74  When pMem is not
15480 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
15490 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65  ll strive to use
154a0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
154b0 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73  ided.** to satis
154c0 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65  fy page cache ne
154d0 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63  eds, falling bac
154e0 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  k to [sqlite3_ma
154f0 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20  lloc()] if.** a 
15500 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
15510 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73  is larger than s
15520 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c  z bytes or if al
15530 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75  l of the pMem bu
15540 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75  ffer.** is exhau
15550 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65  sted..** ^If pMe
15560 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  m is NULL and N 
15570 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
15580 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  n each database 
15590 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f  connection.** do
155a0 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75  es an initial bu
155b0 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  lk allocation fo
155c0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
155d0 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ory.** from [sql
155e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
155f0 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20  ufficient for N 
15600 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e  cache lines if N
15610 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a   is positive or.
15620 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79  ** of -1024*N by
15630 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61  tes if N is nega
15640 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69  tive, . ^If addi
15650 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
15660 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
15670 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
15680 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
15690 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20   the initial.** 
156a0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
156b0 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
156c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
156d0 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f  )] separately fo
156e0 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69  r each.** additi
156f0 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e  onal cache line.
15700 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
15710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15720 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
15730 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
15740 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
15750 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
15760 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
15770 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
15780 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
15790 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
157a0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
157b0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
157c0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
157d0 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
157e0 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
157f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15800 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54  AGECACHE]..** ^T
15810 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15820 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20  _HEAP option is 
15830 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15840 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
15850 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74  iled.** with eit
15860 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
15870 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b  LE_MEMSYS3] or [
15880 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
15890 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72  MSYS5] and retur
158a0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  ns.** [SQLITE_ER
158b0 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20  ROR] if invoked 
158c0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54  otherwise..** ^T
158d0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
158e0 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
158f0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a  TE_CONFIG_HEAP:.
15900 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  ** An 8-byte ali
15910 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
15920 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
15930 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
15940 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
15950 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
15960 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
15970 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
15980 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
15990 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
159a0 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
159b0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
159c0 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
159d0 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
159e0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
159f0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
15a00 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
15a10 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
15a20 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
15a30 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
15a40 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
15a50 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
15a60 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
15a70 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61   NULL then the a
15a80 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
15a90 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
15aa0 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
15ab0 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
15ac0 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
15ad0 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
15ae0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
15af0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
15b00 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
15b10 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
15b20 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
15b30 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
15b40 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
15b50 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
15b60 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
15b70 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
15b80 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
15b90 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
15ba0 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
15bb0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
15bc0 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
15bd0 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
15be0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15c00 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
15c10 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
15c20 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
15c30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15c40 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
15c50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
15c60 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a  nt which is a.**
15c70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
15c80 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
15c90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15ca0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15cb0 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
15cc0 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65  t specifies alte
15cd0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
15ce0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
15cf0 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69   to be used.** i
15d00 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65  n place the mute
15d10 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
15d20 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
15d30 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
15d40 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
15d50 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
15d60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15d70 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15d80 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
15d90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
15da0 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
15db0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
15dc0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
15dd0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
15de0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
15df0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
15e00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15e10 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
15e20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
15e30 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
15e40 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
15e50 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
15e60 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
15e70 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
15e80 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
15e90 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
15ea0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
15eb0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
15ec0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
15ed0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15ee0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15ef0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
15f00 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
15f10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
15f20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15f30 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  GETMUTEX option 
15f40 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15f50 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
15f60 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
15f70 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
15f80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15f90 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15fa0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
15fb0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15fc0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
15fd0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
15fe0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
15ff0 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
16000 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
16010 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
16020 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
16030 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
16040 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
16050 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
16060 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
16070 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
16080 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
16090 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
160a0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
160b0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
160c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
160d0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
160e0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
160f0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
16100 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
16110 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
16120 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
16130 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
16140 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
16150 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
16160 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
16170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
16180 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
16190 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
161a0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
161b0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
161c0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
161d0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
161e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
161f0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
16200 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16210 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
16220 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
16230 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16240 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74  OKASIDE option t
16250 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
16260 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
16270 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  e.** the default
16280 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69   size of lookasi
16290 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63  de memory on eac
162a0 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  h [database conn
162b0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20  ection]..** The 
162c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
162d0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
162e0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
162f0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
16300 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
16310 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
16320 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
16330 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
16340 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
16350 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  (SQLITE_CONFIG_L
16360 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73  OOKASIDE.** sets
16370 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c   the <i>default<
16380 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
16390 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
163a0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
163b0 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f  DE].** option to
163c0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
163d0 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
163e0 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
163f0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
16400 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
16410 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
16420 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
16430 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16440 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
16450 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16460 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
16470 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
16480 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16490 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
164a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
164b0 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
164c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
164d0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
164e0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
164f0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
16500 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e  cifies.** the in
16510 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73  terface to a cus
16520 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
16530 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
16540 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .** ^SQLite make
16550 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
16560 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
16570 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
16580 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
16590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
165a0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
165b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
165c0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
165d0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
165e0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
165f0 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
16600 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16610 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
16620 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
16630 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
16640 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
16650 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
16660 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74  f.** the current
16670 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
16680 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
16690 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
166a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
166b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
166c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
166d0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
166e0 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
166f0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
16700 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
16710 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
16720 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
16730 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
16740 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16750 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
16760 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
16770 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
16780 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
16790 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
167a0 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
167b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
167c0 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
167d0 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
167e0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
167f0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
16800 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
16810 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
16820 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
16830 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
16840 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
16850 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
16860 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
16870 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
16880 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
16890 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
168a0 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
168b0 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
168c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
168d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
168e0 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
168f0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
16900 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
16910 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16920 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
16930 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
16940 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
16950 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
16960 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
16970 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
16980 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
16990 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
169a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
169b0 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
169c0 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
169d0 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
169e0 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
169f0 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
16a00 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
16a10 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
16a20 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
16a30 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
16a40 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
16a50 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
16a60 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
16a70 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
16a80 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
16a90 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
16aa0 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
16ab0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
16ac0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
16ad0 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
16ae0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
16af0 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
16b00 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
16b10 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
16b20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
16b30 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
16b40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
16b50 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
16b60 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
16b70 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
16b80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16b90 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
16ba0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
16bb0 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20  RI.** <dd>^(The 
16bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16bd0 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  I option takes a
16be0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
16bf0 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a   of type int..**
16c00 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   If non-zero, th
16c10 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
16c20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
16c30 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
16c40 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a  meter is zero,.*
16c50 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  * then URI handl
16c60 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
16c70 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20  disabled.)^ ^If 
16c80 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
16c90 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62  globally.** enab
16ca0 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
16cb0 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  es passed to [sq
16cc0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
16cd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
16ce0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
16cf0 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
16d00 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
16d10 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
16d20 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
16d30 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
16d40 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
16d50 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
16d60 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
16d70 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
16d80 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
16d90 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
16da0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66  n is opened. ^If
16db0 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
16dc0 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
16dd0 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
16de0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
16df0 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
16e00 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
16e10 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
16e20 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
16e30 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
16e40 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20  . ^(By default, 
16e50 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
16e60 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
16e70 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
16e80 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
16e90 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
16ea0 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
16eb0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
16ec0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
16ed0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
16ee0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16ef0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c  G_INDEX_SCAN]] <
16f00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16f10 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
16f20 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SCAN.** <dd>^The
16f30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
16f40 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
16f50 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  AN option takes 
16f60 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72  a single integer
16f70 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69  .** argument whi
16f80 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  ch is interprete
16f90 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  d as a boolean i
16fa0 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c  n order to enabl
16fb0 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20  e or disable.** 
16fc0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
16fd0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
16fe0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
16ff0 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70   in the query op
17000 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65  timizer..** ^The
17010 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
17020 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a   is determined.*
17030 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  * by the [SQLITE
17040 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f  _ALLOW_COVERING_
17050 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70  INDEX_SCAN] comp
17060 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
17070 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69   or is "on".** i
17080 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74  f that compile-t
17090 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d  ime option is om
170a0 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62  itted..** The ab
170b0 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65  ility to disable
170c0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
170d0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
170e0 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
170f0 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20  s.** is because 
17100 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79  some incorrectly
17110 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70   coded legacy ap
17120 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74  plications might
17130 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20   malfunction.** 
17140 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a  when the optimiz
17150 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
17160 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65  .  Providing the
17170 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64   ability to.** d
17180 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d  isable the optim
17190 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74  ization allows t
171a0 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20  he older, buggy 
171b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
171c0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
171d0 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20  out change even 
171e0 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69  with newer versi
171f0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
17200 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17210 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b  NFIG_PCACHE]] [[
17220 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17230 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74  TPCACHE]].** <dt
17240 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
17250 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45  CACHE and SQLITE
17260 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
17270 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20  E.** <dd> These 
17280 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f  options are obso
17290 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20  lete and should 
172a0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e  not be used by n
172b0 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79  ew code..** They
172c0 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
172d0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
172e0 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72  atibility but ar
172f0 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  e now no-ops..**
17300 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
17310 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
17320 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  LOG]].** <dt>SQL
17330 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
17340 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  G.** <dd>This op
17350 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
17360 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65  ilable if sqlite
17370 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
17380 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
17390 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20  _ENABLE_SQLLOG] 
173a0 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
173b0 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65  cro defined. The
173c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
173d0 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70  should.** be a p
173e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63  ointer to a func
173f0 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69  tion of type voi
17400 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
17410 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  e3*,const char*,
17420 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65   int)..** The se
17430 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f  cond should be o
17440 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20  f type (void*). 
17450 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  The callback is 
17460 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c  invoked by the l
17470 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72  ibrary.** in thr
17480 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63  ee separate circ
17490 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74  umstances, ident
174a0 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c  ified by the val
174b0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
174c0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
174d0 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75  eter. If the fou
174e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
174f0 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74   0, then the dat
17500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17510 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
17520 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
17530 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  t has just been 
17540 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72  opened. The thir
17550 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f  d argument.** po
17560 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72  ints to a buffer
17570 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
17580 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e  name of the main
17590 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
175a0 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  If the.** fourth
175b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c   parameter is 1,
175c0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   then the SQL st
175d0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65  atement that the
175e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
175f0 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61  .** points to ha
17600 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63  s just been exec
17610 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65  uted. Or, if the
17620 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
17630 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20  r is 2, then.** 
17640 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  the connection b
17650 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74  eing passed as t
17660 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17670 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f  ter is being clo
17680 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  sed. The.** thir
17690 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  d parameter is p
176a0 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68  assed NULL In th
176b0 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61  is case.  An exa
176c0 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68  mple of using th
176d0 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  is.** configurat
176e0 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ion option can b
176f0 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74  e seen in the "t
17700 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f  est_sqllog.c" so
17710 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20  urce file in.** 
17720 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51  the canonical SQ
17730 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65  Lite source tree
17740 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
17750 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
17760 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  P_SIZE]].** <dt>
17770 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
17780 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e  AP_SIZE.** <dd>^
17790 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
177a0 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77  AP_SIZE takes tw
177b0 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  o 64-bit integer
177c0 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29   (sqlite3_int64)
177d0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
177e0 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  are the default 
177f0 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20  mmap size limit 
17800 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  (the default set
17810 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41  ting for.** [PRA
17820 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20  GMA mmap_size]) 
17830 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
17840 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
17850 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
17860 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
17870 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
17880 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62  en by each datab
17890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75  ase connection u
178a0 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74  sing.** either t
178b0 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  he [PRAGMA mmap_
178c0 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f  size] command, o
178d0 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a  r by using the.*
178e0 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
178f0 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
17900 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20  control.  ^(The 
17910 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
17920 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c  mmap size.** wil
17930 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72  l be silently tr
17940 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73  uncated if neces
17950 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20  sary so that it 
17960 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20  does not exceed 
17970 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  the.** compile-t
17980 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70  ime maximum mmap
17990 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65   size set by the
179a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
179b0 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69  MMAP_SIZE] compi
179c0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29  le-time option.)
179d0 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20  ^.** ^If either 
179e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
179f0 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74   option is negat
17a00 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61  ive, then that a
17a10 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68  rgument is.** ch
17a20 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d  anged to its com
17a30 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c  pile-time defaul
17a40 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  t..**.** [[SQLIT
17a50 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17a60 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  EAPSIZE]].** <dt
17a70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  >SQLITE_CONFIG_W
17a80 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a  IN32_HEAPSIZE.**
17a90 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17aa0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17ab0 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73  APSIZE option is
17ac0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
17ad0 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  if SQLite is.** 
17ae0 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e  compiled for Win
17af0 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53  dows with the [S
17b00 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c  QLITE_WIN32_MALL
17b10 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OC] pre-processo
17b20 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e  r macro.** defin
17b30 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  ed. ^SQLITE_CONF
17b40 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
17b50 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74  E takes a 32-bit
17b60 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
17b70 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20  r value.** that 
17b80 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61  specifies the ma
17b90 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68  ximum size of th
17ba0 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a  e created heap..
17bb0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17bc0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
17bd0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
17be0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17bf0 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _HDRSZ.** <dd>^T
17c00 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17c10 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70  _PCACHE_HDRSZ op
17c20 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17c30 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17c40 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
17c50 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17c60 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74  r and writes int
17c70 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74  o that integer t
17c80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
17c90 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20  ra.** bytes per 
17ca0 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f  page required fo
17cb0 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b  r each page in [
17cc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
17cd0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
17ce0 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61   amount of extra
17cf0 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
17d00 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e  can change depen
17d10 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70  ding on the comp
17d20 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20  iler,.** target 
17d30 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51  platform, and SQ
17d40 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a  Lite version..**
17d50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17d60 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c  FIG_PMASZ]].** <
17d70 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17d80 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _PMASZ.** <dd>^T
17d90 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17da0 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _PMASZ option ta
17db0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
17dc0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
17dd0 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69  is an unsigned i
17de0 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20  nteger and sets 
17df0 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41  the "Minimum PMA
17e00 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d   Size" for the m
17e10 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20  ultithreaded.** 
17e20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69  sorter to that i
17e30 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66  nteger.  The def
17e40 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41  ault minimum PMA
17e50 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20   Size is set by 
17e60 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
17e70 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d  ORTER_PMASZ] com
17e80 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17e90 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61  .  New threads a
17ea0 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74  re launched.** t
17eb0 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74  o help with sort
17ec0 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e   operations when
17ed0 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73   multithreaded s
17ee0 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61  orting.** is ena
17ef0 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20  bled (using the 
17f00 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d  [PRAGMA threads]
17f10 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68   command) and th
17f20 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74  e amount of cont
17f30 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72  ent.** to be sor
17f40 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20  ted exceeds the 
17f50 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20  page size times 
17f60 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74  the minimum of t
17f70 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61  he.** [PRAGMA ca
17f80 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e  che_size] settin
17f90 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65  g and this value
17fa0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
17fb0 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c  _CONFIG_STMTJRNL
17fc0 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e  _SPILL]].** <dt>
17fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17fe0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20  MTJRNL_SPILL.** 
17ff0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
18000 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
18010 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b  SPILL option tak
18020 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
18030 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62  meter which.** b
18040 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74  ecomes the [stat
18050 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73  ement journal] s
18060 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72  pill-to-disk thr
18070 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74  eshold.  .** [St
18080 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
18090 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65  ] are held in me
180a0 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72  mory until their
180b0 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29   size (in bytes)
180c0 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73  .** exceeds this
180d0 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77   threshold, at w
180e0 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20  hich point they 
180f0 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64  are written to d
18100 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68  isk..** Or if th
18110 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d  e threshold is -
18120 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  1, statement jou
18130 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73  rnals are always
18140 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69   held.** exclusi
18150 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a  vely in memory..
18160 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74  ** Since many st
18170 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
18180 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61   never become la
18190 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65  rge, setting the
181a0 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68   spill.** thresh
181b0 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73  old to a value s
181c0 75 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e  uch as 64KiB can
181d0 20 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20   greatly reduce 
181e0 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a  the amount of.**
181f0 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f   I/O required to
18200 20 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65   support stateme
18210 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  nt rollback..** 
18220 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
18230 65 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69  e for this setti
18240 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  ng is controlled
18250 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
18260 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  TE_STMTJRNL_SPIL
18270 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  L] compile-time 
18280 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  option..**.** [[
18290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f  SQLITE_CONFIG_SO
182a0 52 54 45 52 52 45 46 5f 53 49 5a 45 5d 5d 0a 2a  RTERREF_SIZE]].*
182b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
182c0 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49  FIG_SORTERREF_SI
182d0 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  ZE.** <dd>The SQ
182e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54  LITE_CONFIG_SORT
182f0 45 52 52 45 46 5f 53 49 5a 45 20 6f 70 74 69 6f  ERREF_SIZE optio
18300 6e 20 61 63 63 65 70 74 73 20 61 20 73 69 6e 67  n accepts a sing
18310 6c 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  le parameter.** 
18320 6f 66 20 74 79 70 65 20 28 69 6e 74 29 20 2d 20  of type (int) - 
18330 74 68 65 20 6e 65 77 20 76 61 6c 75 65 20 6f 66  the new value of
18340 20 74 68 65 20 73 6f 72 74 65 72 2d 72 65 66 65   the sorter-refe
18350 72 65 6e 63 65 20 73 69 7a 65 20 74 68 72 65 73  rence size thres
18360 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 61 6c 6c 79  hold..** Usually
18370 2c 20 77 68 65 6e 20 53 51 4c 69 74 65 20 75 73  , when SQLite us
18380 65 73 20 61 6e 20 65 78 74 65 72 6e 61 6c 20 73  es an external s
18390 6f 72 74 20 74 6f 20 6f 72 64 65 72 20 72 65 63  ort to order rec
183a0 6f 72 64 73 20 61 63 63 6f 72 64 69 6e 67 0a 2a  ords according.*
183b0 2a 20 74 6f 20 61 6e 20 4f 52 44 45 52 20 42 59  * to an ORDER BY
183c0 20 63 6c 61 75 73 65 2c 20 61 6c 6c 20 66 69 65   clause, all fie
183d0 6c 64 73 20 72 65 71 75 69 72 65 64 20 62 79 20  lds required by 
183e0 74 68 65 20 63 61 6c 6c 65 72 20 61 72 65 20 70  the caller are p
183f0 72 65 73 65 6e 74 20 69 6e 20 74 68 65 0a 2a 2a  resent in the.**
18400 20 73 6f 72 74 65 64 20 72 65 63 6f 72 64 73 2e   sorted records.
18410 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
18420 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 62  ite determines b
18430 61 73 65 64 20 6f 6e 20 74 68 65 20 64 65 63 6c  ased on the decl
18440 61 72 65 64 20 74 79 70 65 0a 2a 2a 20 6f 66 20  ared type.** of 
18450 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  a table column t
18460 68 61 74 20 69 74 73 20 76 61 6c 75 65 73 20 61  hat its values a
18470 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20  re likely to be 
18480 76 65 72 79 20 6c 61 72 67 65 20 2d 20 6c 61 72  very large - lar
18490 67 65 72 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ger.** than the 
184a0 63 6f 6e 66 69 67 75 72 65 64 20 73 6f 72 74 65  configured sorte
184b0 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65  r-reference size
184c0 20 74 68 72 65 73 68 6f 6c 64 20 2d 20 74 68 65   threshold - the
184d0 6e 20 61 20 72 65 66 65 72 65 6e 63 65 0a 2a 2a  n a reference.**
184e0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 65 61   is stored in ea
184f0 63 68 20 73 6f 72 74 65 64 20 72 65 63 6f 72 64  ch sorted record
18500 20 61 6e 64 20 74 68 65 20 72 65 71 75 69 72 65   and the require
18510 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20  d column values 
18520 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  loaded.** from t
18530 68 65 20 64 61 74 61 62 61 73 65 20 61 73 20 72  he database as r
18540 65 63 6f 72 64 73 20 61 72 65 20 72 65 74 75 72  ecords are retur
18550 6e 65 64 20 69 6e 20 73 6f 72 74 65 64 20 6f 72  ned in sorted or
18560 64 65 72 2e 20 54 68 65 20 64 65 66 61 75 6c 74  der. The default
18570 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20 74 68  .** value for th
18580 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 74 6f 20  is option is to 
18590 6e 65 76 65 72 20 75 73 65 20 74 68 69 73 20 6f  never use this o
185a0 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 53 70 65  ptimization. Spe
185b0 63 69 66 79 69 6e 67 20 61 20 0a 2a 2a 20 6e 65  cifying a .** ne
185c0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
185d0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 72 65 73   this option res
185e0 74 6f 72 65 73 20 74 68 65 20 64 65 66 61 75 6c  tores the defaul
185f0 74 20 62 65 68 61 76 69 6f 75 72 2e 0a 2a 2a 20  t behaviour..** 
18600 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
18610 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
18620 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
18630 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
18640 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
18650 4f 52 54 45 52 5f 52 45 46 45 52 45 4e 43 45 53  ORTER_REFERENCES
18660 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
18670 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ption..**.** [[S
18680 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
18690 44 42 5f 4d 41 58 53 49 5a 45 5d 5d 0a 2a 2a 20  DB_MAXSIZE]].** 
186a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
186b0 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 0a  G_MEMDB_MAXSIZE.
186c0 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
186d0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d  E_CONFIG_MEMDB_M
186e0 41 58 53 49 5a 45 20 6f 70 74 69 6f 6e 20 61 63  AXSIZE option ac
186f0 63 65 70 74 73 20 61 20 73 69 6e 67 6c 65 20 70  cepts a single p
18700 61 72 61 6d 65 74 65 72 0a 2a 2a 20 5b 73 71 6c  arameter.** [sql
18710 69 74 65 33 5f 69 6e 74 36 34 5d 20 70 61 72 61  ite3_int64] para
18720 6d 65 74 65 72 20 77 68 69 63 68 20 69 73 20 74  meter which is t
18730 68 65 20 64 65 66 61 75 6c 74 20 6d 61 78 69 6d  he default maxim
18740 75 6d 20 73 69 7a 65 20 66 6f 72 20 61 6e 20 69  um size for an i
18750 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74 61  n-memory.** data
18760 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69  base created usi
18770 6e 67 20 5b 73 71 6c 69 74 65 33 5f 64 65 73 65  ng [sqlite3_dese
18780 72 69 61 6c 69 7a 65 28 29 5d 2e 20 20 54 68 69  rialize()].  Thi
18790 73 20 64 65 66 61 75 6c 74 20 6d 61 78 69 6d 75  s default maximu
187a0 6d 0a 2a 2a 20 73 69 7a 65 20 63 61 6e 20 62 65  m.** size can be
187b0 20 61 64 6a 75 73 74 65 64 20 75 70 20 6f 72 20   adjusted up or 
187c0 64 6f 77 6e 20 66 6f 72 20 69 6e 64 69 76 69 64  down for individ
187d0 75 61 6c 20 64 61 74 61 62 61 73 65 73 20 75 73  ual databases us
187e0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
187f0 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49  TE_FCNTL_SIZE_LI
18800 4d 49 54 5d 20 5b 73 71 6c 69 74 65 33 5f 66 69  MIT] [sqlite3_fi
18810 6c 65 5f 63 6f 6e 74 72 6f 6c 7c 66 69 6c 65 2d  le_control|file-
18820 63 6f 6e 74 72 6f 6c 5d 2e 20 20 49 66 20 74 68  control].  If th
18830 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  is.** configurat
18840 69 6f 6e 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ion setting is n
18850 65 76 65 72 20 75 73 65 64 2c 20 74 68 65 6e 20  ever used, then 
18860 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61 78 69  the default maxi
18870 6d 75 6d 20 69 73 20 64 65 74 65 72 6d 69 6e 65  mum is determine
18880 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
18890 49 54 45 5f 4d 45 4d 44 42 5f 44 45 46 41 55 4c  ITE_MEMDB_DEFAUL
188a0 54 5f 4d 41 58 53 49 5a 45 5d 20 63 6f 6d 70 69  T_MAXSIZE] compi
188b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
188c0 20 49 66 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70   If that.** comp
188d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
188e0 69 73 20 6e 6f 74 20 73 65 74 2c 20 74 68 65 6e  is not set, then
188f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61 78   the default max
18900 69 6d 75 6d 20 69 73 20 31 30 37 33 37 34 31 38  imum is 10737418
18910 32 34 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  24..** </dl>.*/.
18920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18930 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
18940 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
18950 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18960 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
18970 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
18980 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18990 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
189a0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
189b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
189c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
189d0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
189e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
189f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18a00 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
18a10 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
18a20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
18a30 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
18a40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
18a50 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
18a60 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
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 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
18a90 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
18aa0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
18ab0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
18ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
18ad0 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
18ae0 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
18af0 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
18b00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18b10 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
18b20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
18b30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18b40 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
18b50 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
18b60 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
18b70 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18b80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
18b90 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
18ba0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
18bb0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
18bc0 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
18bd0 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
18be0 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
18bf0 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
18c00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18c10 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
18c20 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
18c30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18c40 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
18c50 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
18c60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18c70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
18c80 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
18c90 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
18ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
18cb0 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
18cc0 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
18cd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ce0 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
18cf0 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
18d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18d10 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
18d20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
18d30 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
18d40 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
18d50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
18d60 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
18d70 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
18d80 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
18d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18da0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
18db0 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
18dc0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
18dd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
18de0 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
18df0 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
18e00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18e10 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
18e20 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
18e30 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
18e40 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
18e50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18e60 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
18e70 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
18e80 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
18e90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18ea0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
18eb0 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
18ec0 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  psz */.#define S
18ed0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
18ee0 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SZ              
18ef0 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64   25  /* unsigned
18f00 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64   int szPma */.#d
18f10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18f20 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
18f30 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69  LL      26  /* i
18f40 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
18f50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18f60 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 20  G_SMALL_MALLOC  
18f70 20 20 20 20 20 20 32 37 20 20 2f 2a 20 62 6f 6f        27  /* boo
18f80 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
18f90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f  SQLITE_CONFIG_SO
18fa0 52 54 45 52 52 45 46 5f 53 49 5a 45 20 20 20 20  RTERREF_SIZE    
18fb0 20 20 32 38 20 20 2f 2a 20 69 6e 74 20 6e 42 79    28  /* int nBy
18fc0 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
18fd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44  LITE_CONFIG_MEMD
18fe0 42 5f 4d 41 58 53 49 5a 45 20 20 20 20 20 20 20  B_MAXSIZE       
18ff0 32 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69  29  /* sqlite3_i
19000 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  nt64 */../*.** C
19010 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
19020 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
19030 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
19040 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
19050 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
19060 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
19070 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
19080 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
19090 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
190a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
190b0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
190c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
190d0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
190e0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
190f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
19100 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
19110 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
19120 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
19130 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
19140 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
19150 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
19160 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
19170 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
19180 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
19190 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
191a0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
191b0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
191c0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
191d0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
191e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
191f0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
19200 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
19210 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
19220 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
19230 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
19240 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
19250 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
19260 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
19270 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46   [[SQLITE_DBCONF
19280 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 0a 2a  IG_LOOKASIDE]].*
19290 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
192a0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
192b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
192c0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
192d0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
192e0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
192f0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
19300 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
19310 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
19320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
19330 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
19340 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
19350 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19360 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
19370 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
19380 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
19390 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
193a0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
193b0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
193c0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
193d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
193e0 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
193f0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19400 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
19410 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
19420 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
19430 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
19440 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
19450 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
19460 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
19470 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
19480 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19490 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
194a0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
194b0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
194c0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
194d0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
194e0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
194f0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
19500 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
19510 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
19520 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
19530 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
19540 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
19550 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
19560 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
19570 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
19580 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
19590 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
195a0 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
195b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
195c0 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
195d0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
195e0 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
195f0 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
19600 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
19610 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
19620 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
19630 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
19640 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
19650 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
19660 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
19670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
19680 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
19690 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
196a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
196b0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
196c0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
196d0 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
196e0 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
196f0 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
19700 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
19710 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
19720 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
19730 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
19740 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
19750 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
19760 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
19770 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
19780 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
19790 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
197a0 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
197b0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
197c0 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
197d0 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
197e0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
197f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
19800 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19810 41 42 4c 45 5f 46 4b 45 59 5d 5d 0a 2a 2a 20 3c  ABLE_FKEY]].** <
19820 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19830 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
19840 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
19850 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
19860 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
19870 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
19880 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
19890 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
198a0 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
198b0 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
198c0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
198d0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
198e0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
198f0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
19900 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
19910 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
19920 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
19930 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
19940 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
19950 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
19960 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
19970 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
19980 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19990 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
199a0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
199b0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
199c0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
199d0 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
199e0 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
199f0 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
19a00 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
19a10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19a20 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
19a30 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
19a40 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
19a50 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
19a60 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
19a70 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
19a80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
19a90 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19aa0 54 52 49 47 47 45 52 5d 5d 0a 2a 2a 20 3c 64 74  TRIGGER]].** <dt
19ab0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
19ac0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
19ad0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
19ae0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
19af0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
19b00 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
19b10 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
19b20 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
19b30 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
19b40 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
19b50 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
19b60 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
19b70 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
19b80 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
19b90 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
19ba0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
19bb0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
19bc0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
19bd0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
19be0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
19bf0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
19c00 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
19c10 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
19c20 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
19c30 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19c40 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
19c50 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
19c60 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
19c70 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
19c80 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
19c90 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
19ca0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
19cb0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
19cc0 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
19cd0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
19ce0 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
19cf0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
19d00 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53  ONFIG_ENABLE_FTS
19d10 33 5f 54 4f 4b 45 4e 49 5a 45 52 5d 5d 0a 2a 2a  3_TOKENIZER]].**
19d20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19d30 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
19d40 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
19d50 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
19d60 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
19d70 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
19d80 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
19d90 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
19da0 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
19db0 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
19dc0 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
19dd0 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
19de0 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
19df0 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
19e00 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
19e10 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
19e20 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
19e30 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
19e40 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
19e50 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
19e60 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
19e70 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
19e80 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19e90 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
19ea0 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
19eb0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
19ec0 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
19ed0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
19ee0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
19ef0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
19f00 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
19f10 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
19f20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
19f30 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
19f40 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
19f50 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
19f60 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
19f70 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
19f80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
19f90 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
19fa0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
19fb0 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
19fc0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19fd0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
19fe0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
19ff0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a000 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
1a010 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
1a020 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1a030 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c  _LOAD_EXTENSION<
1a040 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
1a050 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
1a060 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
1a070 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69  isable the [sqli
1a080 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
1a090 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  on()].** interfa
1a0a0 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79  ce independently
1a0b0 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78   of the [load_ex
1a0c0 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66  tension()] SQL f
1a0d0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
1a0e0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1a0f0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1a100 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72  ] API enables or
1a110 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74   disables both t
1a120 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c  he.** C-API [sql
1a130 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
1a140 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53  ion()] and the S
1a150 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61  QL function [loa
1a160 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  d_extension()]..
1a170 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
1a180 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
1a190 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
1a1a0 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61  When the first a
1a1b0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
1a1c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20  interface is 1, 
1a1d0 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d  then only the C-
1a1e0 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65  API is.** enable
1a1f0 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  d and the SQL fu
1a200 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64  nction remains d
1a210 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65  isabled.  If the
1a220 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1a230 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  to.** this inter
1a240 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20  face is 0, then 
1a250 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61  both the C-API a
1a260 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
1a270 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64  ion are disabled
1a280 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73  ..** If the firs
1a290 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31  t argument is -1
1a2a0 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  , then no change
1a2b0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74  s are made to st
1a2c0 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68  ate of either th
1a2d0 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68  e.** C-API or th
1a2e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  e SQL function..
1a2f0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
1a300 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1a310 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1a320 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
1a330 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
1a340 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
1a350 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  hether [sqlite3_
1a360 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1a370 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
1a380 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
1a390 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  abled following 
1a3a0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
1a3b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a3c0 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c   may.** be a NUL
1a3d0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68  L pointer, in wh
1a3e0 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
1a3f0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
1a400 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a  reported back..*
1a410 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
1a420 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a430 4d 41 49 4e 44 42 4e 41 4d 45 5d 5d 20 3c 64 74  MAINDBNAME]] <dt
1a440 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1a450 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e  _MAINDBNAME</dt>
1a460 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
1a470 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
1a480 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65   change the name
1a490 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64   of the "main" d
1a4a0 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d  atabase.** schem
1a4b0 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72  a.  ^The sole ar
1a4c0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
1a4d0 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e  ter to a constan
1a4e0 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  t UTF8 string.**
1a4f0 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f   which will beco
1a500 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d  me the new schem
1a510 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20  a name in place 
1a520 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c  of "main".  ^SQL
1a530 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
1a540 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
1a550 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65  he new main sche
1a560 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20  ma name string, 
1a570 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  so the applicati
1a580 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72  on.** must ensur
1a590 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d  e that the argum
1a5a0 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ent passed into 
1a5b0 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70  this DBCONFIG op
1a5c0 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65  tion is unchange
1a5d0 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72  d.** until after
1a5e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a5f0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
1a600 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1a610 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
1a620 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
1a630 53 45 5d 5d 20 0a 2a 2a 20 3c 64 74 3e 53 51 4c  SE]] .** <dt>SQL
1a640 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
1a650 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64  CKPT_ON_CLOSE</d
1a660 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c  t>.** <dd> Usual
1a670 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62  ly, when a datab
1a680 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20  ase in wal mode 
1a690 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74  is closed or det
1a6a0 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a  ached from a .**
1a6b0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
1a6c0 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20  , SQLite checks 
1a6d0 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61  if this will mea
1a6e0 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65  n that there are
1a6f0 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e   now no .** conn
1a700 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74  ections at all t
1a710 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  o the database. 
1a720 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72  If so, it perfor
1a730 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20  ms a checkpoint 
1a740 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65  .** operation be
1a750 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65  fore closing the
1a760 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69   connection. Thi
1a770 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20  s option may be 
1a780 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72  used to.** overr
1a790 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f  ide this behavio
1a7a0 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61  ur. The first pa
1a7b0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
1a7c0 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e  o this operation
1a7d0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
1a7e0 72 20 2d 20 70 6f 73 69 74 69 76 65 20 74 6f 20  r - positive to 
1a7f0 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69  disable checkpoi
1a800 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72  nts-on-close, or
1a810 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65   zero (the.** de
1a820 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65  fault) to enable
1a830 20 74 68 65 6d 2c 20 61 6e 64 20 6e 65 67 61 74   them, and negat
1a840 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
1a850 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
1a860 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
1a870 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
1a880 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1a890 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77  nteger.** into w
1a8a0 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20  hich is written 
1a8b0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
1a8c0 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b  te whether check
1a8d0 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a  points-on-close.
1a8e0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73  ** have been dis
1a8f0 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65  abled - 0 if the
1a900 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c  y are not disabl
1a910 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72  ed, 1 if they ar
1a920 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  e..** </dd>.**.*
1a930 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1a940 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 5d  FIG_ENABLE_QPSG]
1a950 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  ] <dt>SQLITE_DBC
1a960 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
1a970 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28  G</dt>.** <dd>^(
1a980 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  The SQLITE_DBCON
1a990 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20  FIG_ENABLE_QPSG 
1a9a0 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73  option activates
1a9b0 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a   or deactivates.
1a9c0 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c  ** the [query pl
1a9d0 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20  anner stability 
1a9e0 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47  guarantee] (QPSG
1a9f0 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50 53  ).  When the QPS
1aa00 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20  G is active,.** 
1aa10 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65  a single SQL que
1aa20 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ry statement wil
1aa30 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
1aa40 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
1aa50 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
1aa60 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e   values of [boun
1aa70 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e  d parameters].)^
1aa80 20 54 68 65 20 51 50 53 47 20 64 69 73 61 62 6c   The QPSG disabl
1aa90 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70  es some query op
1aaa0 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74  timizations.** t
1aab0 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20  hat look at the 
1aac0 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20  values of bound 
1aad0 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63  parameters, whic
1aae0 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20  h can make some 
1aaf0 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65  queries.** slowe
1ab00 72 2e 20 20 42 75 74 20 74 68 65 20 51 50 53 47  r.  But the QPSG
1ab10 20 68 61 73 20 74 68 65 20 61 64 76 61 6e 74 61   has the advanta
1ab20 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69  ge of more predi
1ab30 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  ctable behavior.
1ab40 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50    With.** the QP
1ab50 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74  SG active, SQLit
1ab60 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73  e will always us
1ab70 65 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79  e the same query
1ab80 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65   plan in the fie
1ab90 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65  ld as.** was use
1aba0 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
1abb0 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20   in the lab..** 
1abc0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1abd0 6e 74 20 74 6f 20 74 68 69 73 20 73 65 74 74 69  nt to this setti
1abe0 6e 67 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ng is an integer
1abf0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
1ac00 69 73 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 51  isable .** the Q
1ac10 50 53 47 2c 20 70 6f 73 69 74 69 76 65 20 74 6f  PSG, positive to
1ac20 20 65 6e 61 62 6c 65 20 51 50 53 47 2c 20 6f 72   enable QPSG, or
1ac30 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
1ac40 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  ve the setting.*
1ac50 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 54 68 65  * unchanged. The
1ac60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1ac70 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1ac80 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1ac90 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
1aca0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1acb0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1acc0 20 74 68 65 20 51 50 53 47 20 69 73 20 64 69 73   the QPSG is dis
1acd0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
1ace0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
1acf0 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64  is call..** </dd
1ad00 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
1ad10 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45  _DBCONFIG_TRIGGE
1ad20 52 5f 45 51 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  R_EQP]] <dt>SQLI
1ad30 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47  TE_DBCONFIG_TRIG
1ad40 47 45 52 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20  GER_EQP</dt>.** 
1ad50 3c 64 64 3e 20 42 79 20 64 65 66 61 75 6c 74 2c  <dd> By default,
1ad60 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 45   the output of E
1ad70 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41  XPLAIN QUERY PLA
1ad80 4e 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 65 73 20  N commands does 
1ad90 6e 6f 74 20 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  not .** include 
1ada0 6f 75 74 70 75 74 20 66 6f 72 20 61 6e 79 20 6f  output for any o
1adb0 70 65 72 61 74 69 6f 6e 73 20 70 65 72 66 6f 72  perations perfor
1adc0 6d 65 64 20 62 79 20 74 72 69 67 67 65 72 20 70  med by trigger p
1add0 72 6f 67 72 61 6d 73 2e 20 54 68 69 73 0a 2a 2a  rograms. This.**
1ade0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
1adf0 74 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  to set or clear 
1ae00 28 74 68 65 20 64 65 66 61 75 6c 74 29 20 61 20  (the default) a 
1ae10 66 6c 61 67 20 74 68 61 74 20 67 6f 76 65 72 6e  flag that govern
1ae20 73 20 74 68 69 73 0a 2a 2a 20 62 65 68 61 76 69  s this.** behavi
1ae30 6f 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61  or. The first pa
1ae40 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
1ae50 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e  o this operation
1ae60 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d   is an integer -
1ae70 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
1ae80 65 6e 61 62 6c 65 20 6f 75 74 70 75 74 20 66 6f  enable output fo
1ae90 72 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  r trigger progra
1aea0 6d 73 2c 20 6f 72 20 7a 65 72 6f 20 74 6f 20 64  ms, or zero to d
1aeb0 69 73 61 62 6c 65 20 69 74 2c 0a 2a 2a 20 6f 72  isable it,.** or
1aec0 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
1aed0 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
1aee0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
1aef0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1af00 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1af10 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1af20 6f 20 77 68 69 63 68 20 69 73 20 77 72 69 74 74  o which is writt
1af30 65 6e 20 0a 2a 2a 20 30 20 6f 72 20 31 20 74 6f  en .** 0 or 1 to
1af40 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
1af50 72 20 6f 75 74 70 75 74 2d 66 6f 72 2d 74 72 69  r output-for-tri
1af60 67 67 65 72 73 20 68 61 73 20 62 65 65 6e 20 64  ggers has been d
1af70 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 0a  isabled - 0 if .
1af80 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 64 69 73  ** it is not dis
1af90 61 62 6c 65 64 2c 20 31 20 69 66 20 69 74 20 69  abled, 1 if it i
1afa0 73 2e 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  s.  .** </dd>.**
1afb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
1afc0 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1afd0 42 41 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  BASE]] <dt>SQLIT
1afe0 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54  E_DBCONFIG_RESET
1aff0 5f 44 41 54 41 42 41 53 45 3c 2f 64 74 3e 0a 2a  _DATABASE</dt>.*
1b000 2a 20 3c 64 64 3e 20 53 65 74 20 74 68 65 20 53  * <dd> Set the S
1b010 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52  QLITE_DBCONFIG_R
1b020 45 53 45 54 5f 44 41 54 41 42 41 53 45 20 66 6c  ESET_DATABASE fl
1b030 61 67 20 61 6e 64 20 74 68 65 6e 20 72 75 6e 0a  ag and then run.
1b040 2a 2a 20 5b 56 41 43 55 55 4d 5d 20 69 6e 20 6f  ** [VACUUM] in o
1b050 72 64 65 72 20 74 6f 20 72 65 73 65 74 20 61 20  rder to reset a 
1b060 64 61 74 61 62 61 73 65 20 62 61 63 6b 20 74 6f  database back to
1b070 20 61 6e 20 65 6d 70 74 79 20 64 61 74 61 62 61   an empty databa
1b080 73 65 0a 2a 2a 20 77 69 74 68 20 6e 6f 20 73 63  se.** with no sc
1b090 68 65 6d 61 20 61 6e 64 20 6e 6f 20 63 6f 6e 74  hema and no cont
1b0a0 65 6e 74 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ent. The followi
1b0b0 6e 67 20 70 72 6f 63 65 73 73 20 77 6f 72 6b 73  ng process works
1b0c0 20 65 76 65 6e 20 66 6f 72 0a 2a 2a 20 61 20 62   even for.** a b
1b0d0 61 64 6c 79 20 63 6f 72 72 75 70 74 65 64 20 64  adly corrupted d
1b0e0 61 74 61 62 61 73 65 20 66 69 6c 65 3a 0a 2a 2a  atabase file:.**
1b0f0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
1b100 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b110 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 65 77 6c  nnection is newl
1b120 79 20 6f 70 65 6e 65 64 2c 20 6d 61 6b 65 20 73  y opened, make s
1b130 75 72 65 20 69 74 20 68 61 73 20 72 65 61 64 20  ure it has read 
1b140 74 68 65 0a 2a 2a 20 20 20 20 20 20 64 61 74 61  the.**      data
1b150 62 61 73 65 20 73 63 68 65 6d 61 20 62 79 20 70  base schema by p
1b160 72 65 70 61 72 69 6e 67 20 74 68 65 6e 20 64 69  reparing then di
1b170 73 63 61 72 64 69 6e 67 20 73 6f 6d 65 20 71 75  scarding some qu
1b180 65 72 79 20 61 67 61 69 6e 73 74 20 74 68 65 0a  ery against the.
1b190 2a 2a 20 20 20 20 20 20 64 61 74 61 62 61 73 65  **      database
1b1a0 2c 20 6f 72 20 63 61 6c 6c 69 6e 67 20 73 71 6c  , or calling sql
1b1b0 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
1b1c0 6e 5f 6d 65 74 61 64 61 74 61 28 29 2c 20 69 67  n_metadata(), ig
1b1d0 6e 6f 72 69 6e 67 20 61 6e 79 0a 2a 2a 20 20 20  noring any.**   
1b1e0 20 20 20 65 72 72 6f 72 73 2e 20 20 54 68 69 73     errors.  This
1b1f0 20 73 74 65 70 20 69 73 20 6f 6e 6c 79 20 6e 65   step is only ne
1b200 63 65 73 73 61 72 79 20 69 66 20 74 68 65 20 61  cessary if the a
1b210 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 73 69 72  pplication desir
1b220 65 73 20 74 6f 20 6b 65 65 70 0a 2a 2a 20 20 20  es to keep.**   
1b230 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20     the database 
1b240 69 6e 20 57 41 4c 20 6d 6f 64 65 20 61 66 74 65  in WAL mode afte
1b250 72 20 74 68 65 20 72 65 73 65 74 20 69 66 20 69  r the reset if i
1b260 74 20 77 61 73 20 69 6e 20 57 41 4c 20 6d 6f 64  t was in WAL mod
1b270 65 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20  e before.**     
1b280 20 74 68 65 20 72 65 73 65 74 2e 20 20 0a 2a 2a   the reset.  .**
1b290 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62   <li> sqlite3_db
1b2a0 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49  _config(db, SQLI
1b2b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45  TE_DBCONFIG_RESE
1b2c0 54 5f 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30  T_DATABASE, 1, 0
1b2d0 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69  );.** <li> [sqli
1b2e0 74 65 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b  te3_exec](db, "[
1b2f0 56 41 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20  VACUUM]", 0, 0, 
1b300 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  0);.** <li> sqli
1b310 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62  te3_db_config(db
1b320 2c 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  , SQLITE_DBCONFI
1b330 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45  G_RESET_DATABASE
1b340 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c  , 0, 0);.** </ol
1b350 3e 0a 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73  >.** Because res
1b360 65 74 74 69 6e 67 20 61 20 64 61 74 61 62 61 73  etting a databas
1b370 65 20 69 73 20 64 65 73 74 72 75 63 74 69 76 65  e is destructive
1b380 20 61 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c   and irreversibl
1b390 65 2c 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73  e, the.** proces
1b3a0 73 20 72 65 71 75 69 72 65 73 20 74 68 65 20 75  s requires the u
1b3b0 73 65 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75  se of this obscu
1b3c0 72 65 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69  re API and multi
1b3d0 70 6c 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c  ple steps to hel
1b3e0 70 0a 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74  p.** ensure that
1b3f0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70   it does not hap
1b400 70 65 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e  pen by accident.
1b410 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
1b420 44 42 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49  DBCONFIG_DEFENSI
1b430 56 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  VE]] <dt>SQLITE_
1b440 44 42 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49  DBCONFIG_DEFENSI
1b450 56 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  VE</dt>.** <dd>T
1b460 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
1b470 49 47 5f 44 45 46 45 4e 53 49 56 45 20 6f 70 74  IG_DEFENSIVE opt
1b480 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72  ion activates or
1b490 20 64 65 61 63 74 69 76 61 74 65 73 20 74 68 65   deactivates the
1b4a0 0a 2a 2a 20 22 64 65 66 65 6e 73 69 76 65 22 20  .** "defensive" 
1b4b0 66 6c 61 67 20 66 6f 72 20 61 20 64 61 74 61 62  flag for a datab
1b4c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1b4d0 20 57 68 65 6e 20 74 68 65 20 64 65 66 65 6e 73   When the defens
1b4e0 69 76 65 0a 2a 2a 20 66 6c 61 67 20 69 73 20 65  ive.** flag is e
1b4f0 6e 61 62 6c 65 64 2c 20 6c 61 6e 67 75 61 67 65  nabled, language
1b500 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 61   features that a
1b510 6c 6c 6f 77 20 6f 72 64 69 6e 61 72 79 20 53 51  llow ordinary SQ
1b520 4c 20 74 6f 20 0a 2a 2a 20 64 65 6c 69 62 65 72  L to .** deliber
1b530 61 74 65 6c 79 20 63 6f 72 72 75 70 74 20 74 68  ately corrupt th
1b540 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1b550 61 72 65 20 64 69 73 61 62 6c 65 64 2e 20 20 54  are disabled.  T
1b560 68 65 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66  he disabled.** f
1b570 65 61 74 75 72 65 73 20 69 6e 63 6c 75 64 65 20  eatures include 
1b580 62 75 74 20 61 72 65 20 6e 6f 74 20 6c 69 6d 69  but are not limi
1b590 74 65 64 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ted to the follo
1b5a0 77 69 6e 67 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  wing:.** <ul>.**
1b5b0 20 3c 6c 69 3e 20 54 68 65 20 5b 50 52 41 47 4d   <li> The [PRAGM
1b5c0 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d  A writable_schem
1b5d0 61 3d 4f 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  a=ON] statement.
1b5e0 0a 2a 2a 20 3c 6c 69 3e 20 57 72 69 74 65 73 20  .** <li> Writes 
1b5f0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 5f 64  to the [sqlite_d
1b600 62 70 61 67 65 5d 20 76 69 72 74 75 61 6c 20 74  bpage] virtual t
1b610 61 62 6c 65 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 69  able..** <li> Di
1b620 72 65 63 74 20 77 72 69 74 65 73 20 74 6f 20 5b  rect writes to [
1b630 73 68 61 64 6f 77 20 74 61 62 6c 65 73 5d 2e 0a  shadow tables]..
1b640 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64  ** </ul>.** </dd
1b650 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  >.** </dl>.*/.#d
1b660 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1b670 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45  ONFIG_MAINDBNAME
1b680 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 30              1000
1b690 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20   /* const char* 
1b6a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b6b0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
1b6c0 53 49 44 45 20 20 20 20 20 20 20 20 20 20 20 20  SIDE            
1b6d0 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69   1001 /* void* i
1b6e0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
1b6f0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1b700 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20  G_ENABLE_FKEY   
1b710 20 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20          1002 /* 
1b720 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1b730 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1b740 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
1b750 45 52 20 20 20 20 20 20 20 20 31 30 30 33 20 2f  ER        1003 /
1b760 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1b770 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1b780 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53  ONFIG_ENABLE_FTS
1b790 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34  3_TOKENIZER 1004
1b7a0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1b7b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b7c0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
1b7d0 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30  OAD_EXTENSION 10
1b7e0 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  05 /* int int* *
1b7f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b800 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50  _DBCONFIG_NO_CKP
1b810 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20  T_ON_CLOSE      
1b820 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1006 /* int int*
1b830 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b840 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1b850 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20 20 20  LE_QPSG         
1b860 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e    1007 /* int in
1b870 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1b880 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52  LITE_DBCONFIG_TR
1b890 49 47 47 45 52 5f 45 51 50 20 20 20 20 20 20 20  IGGER_EQP       
1b8a0 20 20 20 20 31 30 30 38 20 2f 2a 20 69 6e 74 20      1008 /* int 
1b8b0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1b8c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b8d0 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 20 20  RESET_DATABASE  
1b8e0 20 20 20 20 20 20 31 30 30 39 20 2f 2a 20 69 6e        1009 /* in
1b8f0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1b900 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1b910 47 5f 44 45 46 45 4e 53 49 56 45 20 20 20 20 20  G_DEFENSIVE     
1b920 20 20 20 20 20 20 20 20 31 30 31 30 20 2f 2a 20          1010 /* 
1b930 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1b940 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1b950 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20 20  FIG_MAX         
1b960 20 20 20 20 20 20 20 20 20 20 31 30 31 30 20 2f            1010 /
1b970 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e 46  * Largest DBCONF
1b980 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  IG */../*.** CAP
1b990 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
1b9a0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
1b9b0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
1b9c0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1b9d0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
1b9e0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
1b9f0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
1ba00 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
1ba10 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
1ba20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1ba30 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
1ba40 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
1ba50 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
1ba60 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
1ba70 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1ba80 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
1ba90 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1baa0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1bab0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1bac0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
1bad0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
1bae0 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
1baf0 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
1bb00 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f  t Rowid.** METHO
1bb10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1bb20 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
1bb30 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
1bb40 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
1bb50 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
1bb60 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
1bb70 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
1bb80 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
1bb90 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
1bba0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
1bbb0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
1bbc0 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
1bbd0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
1bbe0 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
1bbf0 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
1bc00 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
1bc10 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
1bc20 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
1bc30 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
1bc40 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
1bc50 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
1bc60 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
1bc70 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
1bc80 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
1bc90 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
1bca0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
1bcb0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
1bcc0 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
1bcd0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1bce0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
1bcf0 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72  erface usually r
1bd00 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
1bd10 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73  d] of.** the mos
1bd20 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
1bd30 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
1bd40 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
1bd50 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
1bd60 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
1bd70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
1bd80 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
1bd90 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
1bda0 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  bles are not.** 
1bdb0 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f  recorded. ^If no
1bdc0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1bdd0 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
1bde0 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65   tables have eve
1bdf0 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f  r occurred .** o
1be00 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1be10 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65  onnection D, the
1be20 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
1be30 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
1be40 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e  eturns .** zero.
1be50 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61  .**.** As well a
1be60 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f  s being set auto
1be70 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77  matically as row
1be80 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69  s are inserted i
1be90 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  nto database.** 
1bea0 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75  tables, the valu
1beb0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
1bec0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
1bed0 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c  be set explicitl
1bee0 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  y by.** [sqlite3
1bef0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1bf00 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20  _rowid()].**.** 
1bf10 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62  Some virtual tab
1bf20 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1bf30 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f  ns may INSERT ro
1bf40 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ws into rowid ta
1bf50 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20  bles as.** part 
1bf60 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20  of committing a 
1bf70 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67  transaction (e.g
1bf80 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  . to flush data 
1bf90 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d  accumulated in m
1bfa0 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b  emory.** to disk
1bfb0 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20  ). In this case 
1bfc0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1bfd0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
1bfe0 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77  n return the row
1bff0 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  id.** associated
1c000 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65   with these inte
1c010 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72  rnal INSERT oper
1c020 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65  ations, which le
1c030 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74  ads to .** unint
1c040 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20  uitive results. 
1c050 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
1c060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68  plementations th
1c070 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72  at do write to r
1c080 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69  owid.** tables i
1c090 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61  n this way can a
1c0a0 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65  void this proble
1c0b0 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74  m by restoring t
1c0c0 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20  he original .** 
1c0d0 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e  rowid value usin
1c0e0 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  g [sqlite3_set_l
1c0f0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1c100 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72  ()] before retur
1c110 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c  ning .** control
1c120 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a   to the user..**
1c130 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
1c140 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
1c150 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65  in a trigger the
1c160 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
1c170 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ill .** return t
1c180 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
1c190 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61  e inserted row a
1c1a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
1c1b0 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e  igger is .** run
1c1c0 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74  ning. Once the t
1c1d0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
1c1e0 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
1c1f0 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
1c200 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
1c210 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
1c220 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
1c230 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e  igger was fired.
1c240 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
1c250 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
1c260 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
1c270 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
1c280 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
1c290 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
1c2a0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
1c2b0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
1c2c0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
1c2d0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
1c2e0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
1c2f0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
1c300 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
1c310 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
1c320 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
1c330 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
1c340 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1c350 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
1c360 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
1c370 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
1c380 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
1c390 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
1c3a0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
1c3b0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
1c3c0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
1c3d0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
1c3e0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
1c3f0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
1c400 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
1c410 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
1c420 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
1c430 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
1c440 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
1c450 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
1c460 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1c470 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1c480 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
1c490 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
1c4a0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
1c4b0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
1c4c0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
1c4d0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
1c4e0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
1c4f0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
1c500 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
1c510 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
1c520 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
1c530 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
1c540 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
1c550 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
1c560 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1c570 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1c580 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
1c590 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
1c5a0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
1c5b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
1c5c0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
1c5d0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1c5e0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
1c5f0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
1c600 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
1c610 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1c620 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
1c630 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1c640 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
1c650 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1c660 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
1c670 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
1c680 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
1c690 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
1c6a0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
1c6b0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
1c6c0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1c6d0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1c6e0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1c6f0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
1c700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1c710 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72  t the Last Inser
1c720 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a  t Rowid value..*
1c730 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1c740 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
1c750 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1c760 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20  ert_rowid(D, R) 
1c770 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68  method allows th
1c780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
1c790 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75  .** set the valu
1c7a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61  e returned by ca
1c7b0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61  lling sqlite3_la
1c7c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1c7d0 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68  D) to R .** with
1c7e0 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20  out inserting a 
1c7f0 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74  row into the dat
1c800 61 62 61 73 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  abase..*/.SQLITE
1c810 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1c820 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1c830 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
1c840 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
1c850 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c860 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
1c870 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
1c880 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
1c890 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1c8a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1c8b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1c8c0 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c  f rows modified,
1c8d0 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20   inserted or.** 
1c8e0 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
1c8f0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
1c900 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
1c910 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a  PDATE or DELETE.
1c920 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  ** statement on 
1c930 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c940 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  nection specifie
1c950 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61  d by the only pa
1c960 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65  rameter..** ^Exe
1c970 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
1c980 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
1c990 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
1c9a0 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65  modify the value
1c9b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
1c9c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
1c9d0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67  *.** ^Only chang
1c9e0 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79  es made directly
1c9f0 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
1ca00 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1ca10 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a   statement are.*
1ca20 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61  * considered - a
1ca30 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
1ca40 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41   caused by [CREA
1ca50 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
1ca60 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72  ggers], .** [for
1ca70 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1ca80 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63  ] or [REPLACE] c
1ca90 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1caa0 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75  tion are not cou
1cab0 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61  nted..** .** Cha
1cac0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1cad0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1cae0 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54  ted by .** [INST
1caf0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c  EAD OF trigger |
1cb00 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
1cb10 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  gers] are not co
1cb20 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75  unted. ^The valu
1cb30 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  e .** returned b
1cb40 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1cb50 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  s() immediately 
1cb60 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c  after an INSERT,
1cb70 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44   UPDATE or .** D
1cb80 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1cb90 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73  run on a view is
1cba0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e   always zero. On
1cbb0 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
1cbc0 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c  to real .** tabl
1cbd0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
1cbe0 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65  **.** Things are
1cbf0 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
1cc00 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33  d if the sqlite3
1cc10 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
1cc20 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74  ion is.** execut
1cc30 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67  ed while a trigg
1cc40 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75  er program is ru
1cc50 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20  nning. This may 
1cc60 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a  happen if the.**
1cc70 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68   program uses th
1cc80 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1cc90 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69   function], or i
1cca0 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c  f some other cal
1ccb0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1ccc0 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65  n invokes sqlite
1ccd0 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65  3_changes() dire
1cce0 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c  ctly. Essentiall
1ccf0 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y:.** .** <ul>.*
1cd00 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72  *   <li> ^(Befor
1cd10 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69  e entering a tri
1cd20 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65  gger program the
1cd30 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1cd40 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c  by.**        sql
1cd50 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1cd60 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64  unction is saved
1cd70 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67  . After the trig
1cd80 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20  ger program .** 
1cd90 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73         has finis
1cda0 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61  hed, the origina
1cdb0 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f  l value is resto
1cdc0 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20  red.)^.** .**   
1cdd0 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20  <li> ^(Within a 
1cde0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1cdf0 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44  each INSERT, UPD
1ce00 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a  ATE and DELETE .
1ce10 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d  **        statem
1ce20 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c  ent sets the val
1ce30 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1ce40 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1ce50 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e   .**        upon
1ce60 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e   completion as n
1ce70 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65  ormal. Of course
1ce80 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c  , this value wil
1ce90 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a  l not include .*
1cea0 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61  *        any cha
1ceb0 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62  nges performed b
1cec0 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20  y sub-triggers, 
1ced0 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  as the sqlite3_c
1cee0 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
1cef0 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62      value will b
1cf00 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74  e saved and rest
1cf10 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20  ored after each 
1cf20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20  sub-trigger has 
1cf30 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  run.)^.** </ul>.
1cf40 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61  ** .** ^This mea
1cf50 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63  ns that if the c
1cf60 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1cf70 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61  ction (or simila
1cf80 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79  r) is used.** by
1cf90 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52   the first INSER
1cfa0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1cfb0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
1cfc0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
1cfd0 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  it .** returns t
1cfe0 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20  he value as set 
1cff0 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67  when the calling
1d000 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e   statement began
1d010 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
1d020 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79  If it is used by
1d030 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73   the second or s
1d040 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73  ubsequent such s
1d050 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1d060 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72  a trigger .** pr
1d070 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65  ogram, the value
1d080 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63   returned reflec
1d090 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ts the number of
1d0a0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62   rows modified b
1d0b0 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f  y the .** previo
1d0c0 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  us INSERT, UPDAT
1d0d0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
1d0e0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
1d0f0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
1d100 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1d110 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1d120 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1d130 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1d140 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1d150 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1d160 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1d170 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
1d180 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
1d190 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1d1a0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1d1b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a  **.** See also:.
1d1c0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1d1d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
1d1e0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
1d1f0 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c 69 3e 20  terface.** <li> 
1d200 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  the [count_chang
1d210 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c  es pragma].** <l
1d220 69 3e 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  i> the [changes(
1d230 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a  ) SQL function].
1d240 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 64 61 74  ** <li> the [dat
1d250 61 5f 76 65 72 73 69 6f 6e 20 70 72 61 67 6d 61  a_version pragma
1d260 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51  ].** </ul>.*/.SQ
1d270 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1d280 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
1d290 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1d2a0 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
1d2b0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1d2c0 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1d2d0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1d2e0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1d2f0 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
1d300 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1d310 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
1d320 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1d330 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
1d340 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
1d350 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
1d360 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
1d370 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
1d380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
1d390 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
1d3a0 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
1d3b0 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
1d3c0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1d3d0 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
1d3e0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1d3f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1d400 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
1d410 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1d420 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
1d430 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
1d440 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
1d450 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
1d460 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1d470 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
1d480 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
1d490 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
1d4a0 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
1d4b0 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
1d4c0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
1d4d0 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
1d4e0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
1d4f0 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
1d500 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
1d510 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
1d520 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  t counted..**.**
1d530 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   The [sqlite3_to
1d540 74 61 6c 5f 63 68 61 6e 67 65 73 28 44 29 5d 20  tal_changes(D)] 
1d550 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1d560 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 65  eports the numbe
1d570 72 0a 2a 2a 20 6f 66 20 72 6f 77 73 20 74 68 61  r.** of rows tha
1d580 74 20 63 68 61 6e 67 65 64 20 64 75 65 20 74 6f  t changed due to
1d590 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 72   SQL statement r
1d5a0 75 6e 20 61 67 61 69 6e 73 74 20 64 61 74 61 62  un against datab
1d5b0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
1d5c0 6e 20 44 2e 20 20 41 6e 79 20 63 68 61 6e 67 65  n D.  Any change
1d5d0 73 20 62 79 20 6f 74 68 65 72 20 64 61 74 61 62  s by other datab
1d5e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1d5f0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20  are ignored..** 
1d600 54 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65  To detect change
1d610 73 20 61 67 61 69 6e 73 74 20 61 20 64 61 74 61  s against a data
1d620 62 61 73 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f  base file from o
1d630 74 68 65 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ther database.**
1d640 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65   connections use
1d650 20 74 68 65 20 5b 50 52 41 47 4d 41 20 64 61 74   the [PRAGMA dat
1d660 61 5f 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61  a_version] comma
1d670 6e 64 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51  nd or the.** [SQ
1d680 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f  LITE_FCNTL_DATA_
1d690 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63  VERSION] [file c
1d6a0 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20  ontrol]..** .** 
1d6b0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1d6c0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1d6d0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1d6e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d6f0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1d700 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1d710 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1d720 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
1d730 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
1d740 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1d750 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1d760 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1d770 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1d780 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1d790 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1d7a0 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  ce.** <li> the [
1d7b0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1d7c0 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68  agma].** <li> th
1d7d0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1d7e0 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c   function].** <l
1d7f0 69 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72  i> the [data_ver
1d800 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20  sion pragma].** 
1d810 3c 6c 69 3e 20 74 68 65 20 5b 53 51 4c 49 54 45  <li> the [SQLITE
1d820 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53  _FCNTL_DATA_VERS
1d830 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ION] [file contr
1d840 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ol].** </ul>.*/.
1d850 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1d860 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1d870 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1d880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d890 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
1d8a0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
1d8b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1d8c0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1d8d0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
1d8e0 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
1d8f0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
1d900 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
1d910 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
1d920 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
1d930 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
1d940 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
1d950 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
1d960 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
1d970 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
1d980 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
1d990 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
1d9a0 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
1d9b0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
1d9c0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
1d9d0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1d9e0 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
1d9f0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1da00 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
1da10 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
1da20 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
1da30 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1da40 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
1da50 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1da60 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
1da70 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
1da80 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1da90 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1daa0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
1dab0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
1dac0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
1dad0 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
1dae0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
1daf0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
1db00 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
1db10 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
1db20 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
1db30 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
1db40 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
1db50 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
1db60 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
1db70 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1db80 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1db90 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1dba0 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1dbb0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1dbc0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1dbd0 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1dbe0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1dbf0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1dc00 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1dc10 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1dc20 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1dc30 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1dc40 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1dc50 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1dc60 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1dc70 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1dc80 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1dc90 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1dca0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1dcb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1dcc0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1dcd0 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1dce0 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1dcf0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1dd00 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1dd10 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1dd20 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1dd30 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1dd40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1dd50 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1dd60 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1dd70 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1dd80 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1dd90 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1dda0 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1ddb0 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1ddc0 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1ddd0 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1dde0 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1ddf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1de00 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1de10 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1de20 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1de30 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1de40 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1de50 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1de60 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1de70 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1de80 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1de90 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1dea0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1deb0 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1dec0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1ded0 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1dee0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1def0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1df00 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1df10 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1df20 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1df30 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1df40 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1df50 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1df60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1df70 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1df80 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1df90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dfa0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1dfb0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1dfc0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1dfd0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1dfe0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1dff0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1e000 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1e010 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1e020 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1e030 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1e040 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1e050 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1e060 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1e070 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1e080 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1e090 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1e0a0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1e0b0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1e0c0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1e0d0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1e0e0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1e0f0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1e100 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1e110 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1e120 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1e130 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1e140 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1e150 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1e160 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1e170 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1e180 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1e190 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1e1a0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1e1b0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1e1c0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1e1d0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1e1e0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1e1f0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1e200 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1e210 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1e220 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1e230 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1e240 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1e250 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1e260 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1e270 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1e280 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1e290 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1e2a0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1e2b0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1e2c0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1e2d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1e2e0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1e2f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1e300 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1e310 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1e320 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1e330 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1e340 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1e350 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1e360 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1e370 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1e380 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1e390 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1e3a0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1e3b0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1e3c0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1e3d0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1e3e0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1e3f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1e400 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1e410 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1e420 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1e430 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1e440 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1e450 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1e460 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1e470 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1e480 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1e490 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1e4a0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1e4b0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1e4c0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1e4d0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1e4e0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1e4f0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1e500 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1e510 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1e520 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1e530 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1e540 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1e550 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1e560 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1e570 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1e580 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1e590 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1e5a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1e5b0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1e5c0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1e5d0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c  te order..*/.SQL
1e5e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1e5f0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
1e600 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53  st char *sql);.S
1e610 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1e620 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1e630 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
1e640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e650 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
1e660 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
1e670 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
1e680 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  rors.** KEYWORDS
1e690 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  : {busy-handler 
1e6a0 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20  callback} {busy 
1e6b0 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  handler}.** METH
1e6c0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1e6d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1e6e0 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
1e6f0 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
1e700 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1e710 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
1e720 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1e730 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
1e740 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1e750 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1e760 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
1e770 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
1e780 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
1e790 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e7a0 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
1e7b0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
1e7c0 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
1e7d0 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
1e7e0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1e7f0 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
1e800 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
1e810 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
1e820 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1e830 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
1e840 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
1e850 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
1e860 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1e870 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
1e880 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
1e890 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1e8a0 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
1e8b0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
1e8c0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1e8d0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
1e8e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
1e8f0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
1e900 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1e910 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1e920 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1e930 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1e940 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1e950 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1e960 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1e970 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1e980 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1e990 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1e9a0 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1e9b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1e9c0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1e9d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1e9e0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1e9f0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1ea00 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1ea10 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
1ea20 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
1ea30 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
1ea40 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1ea50 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1ea60 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1ea70 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1ea80 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1ea90 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1eaa0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1eab0 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
1eac0 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
1ead0 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
1eae0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1eaf0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1eb00 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1eb10 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1eb20 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1eb30 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1eb40 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1eb50 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1eb60 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1eb70 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1eb80 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1eb90 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1eba0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1ebb0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1ebc0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1ebd0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1ebe0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1ebf0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1ec00 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1ec10 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1ec20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1ec30 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1ec40 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1ec50 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1ec60 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1ec70 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1ec80 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1ec90 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1eca0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1ecb0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1ecc0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1ecd0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1ece0 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1ecf0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1ed00 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1ed10 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1ed20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1ed30 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1ed40 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1ed50 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1ed60 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1ed70 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1ed80 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1ed90 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1eda0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1edb0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1edc0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1edd0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1ede0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1edf0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1ee00 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1ee10 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1ee20 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1ee30 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1ee40 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1ee50 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1ee60 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1ee70 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1ee80 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1ee90 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1eea0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1eeb0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1eec0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1eed0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1eee0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1eef0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1ef00 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1ef10 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1ef20 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1ef30 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1ef40 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1ef50 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1ef60 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1ef70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1ef80 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1ef90 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1efa0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1efb0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1efc0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1efd0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1efe0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1eff0 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1f000 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1f010 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1f020 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1f030 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1f040 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1f050 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1f060 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1f070 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1f080 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1f090 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1f0a0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1f0b0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1f0c0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1f0d0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1f0e0 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1f0f0 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1f100 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1f110 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1f120 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1f130 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1f140 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1f150 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1f160 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1f170 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1f180 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1f190 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1f1a0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1f1b0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1f1c0 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  dler..*/.SQLITE_
1f1d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1f1e0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1f1f0 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69  ite3*,int(*)(voi
1f200 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a  d*,int),void*);.
1f210 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f220 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
1f230 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  out.** METHOD: s
1f240 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1f250 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
1f260 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
1f270 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
1f280 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
1f290 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
1f2a0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
1f2b0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
1f2c0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
1f2d0 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
1f2e0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
1f2f0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
1f300 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1f310 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1f320 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
1f330 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
1f340 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
1f350 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1f360 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
1f370 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
1f380 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
1f390 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f3a0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
1f3b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
1f3c0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
1f3d0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1f3e0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
1f3f0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
1f400 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
1f410 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
1f420 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
1f430 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1f440 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1f450 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
1f460 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1f470 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1f480 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  at any given mom
1f490 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1f4a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1f4b0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1f4c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1f4d0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1f4e0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1f4f0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1f500 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1f510 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1f520 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  red.)^.**.** See
1f530 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20   also:  [PRAGMA 
1f540 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f  busy_timeout].*/
1f550 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1f560 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1f570 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1f580 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1f590 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1f5a0 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1f5b0 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1f5c0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1f5d0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ite3.**.** This 
1f5e0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1f5f0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1f600 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1f610 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1f620 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1f630 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1f640 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1f650 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1f660 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1f670 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1f680 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1f690 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1f6a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1f6b0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1f6c0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1f6d0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1f6e0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1f6f0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1f700 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1f710 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1f720 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1f730 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1f740 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1f750 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1f760 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1f770 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1f780 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1f790 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1f7a0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1f7b0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1f7c0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1f7d0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1f7e0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1f7f0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1f800 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1f810 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1f820 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1f830 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1f840 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1f850 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1f860 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1f870 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1f880 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1f890 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1f8a0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1f8b0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1f8c0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1f8d0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1f8e0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1f8f0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1f900 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1f910 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1f920 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1f930 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1f940 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1f950 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1f960 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1f970 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1f980 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1f990 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1f9a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1f9b0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1f9c0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1f9d0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1f9e0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1f9f0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1fa00 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1fa10 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1fa20 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1fa30 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1fa40 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1fa50 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1fa60 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1fa70 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1fa80 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1fa90 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1faa0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1fab0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1fac0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1fad0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1fae0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1faf0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1fb00 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1fb10 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1fb20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1fb30 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1fb40 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1fb50 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1fb60 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1fb70 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1fb80 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1fb90 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1fba0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1fbb0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1fbc0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1fbd0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1fbe0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1fbf0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1fc00 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1fc10 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1fc20 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1fc30 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1fc40 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1fc50 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1fc60 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1fc70 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1fc80 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1fc90 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1fca0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1fcb0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1fcc0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1fcd0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1fce0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1fcf0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1fd00 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1fd10 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1fd20 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1fd30 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1fd40 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1fd50 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1fd60 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1fd70 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1fd80 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1fd90 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1fda0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1fdb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fdc0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1fdd0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1fde0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1fdf0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1fe00 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1fe10 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1fe20 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1fe30 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1fe40 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1fe50 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1fe60 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1fe70 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1fe80 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1fe90 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1fea0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1feb0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1fec0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1fed0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1fee0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1fef0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1ff00 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1ff10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1ff20 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1ff30 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1ff40 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1ff50 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1ff60 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1ff70 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1ff80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1ff90 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1ffa0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1ffb0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1ffc0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1ffd0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1ffe0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1fff0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
20000 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
20010 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
20020 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
20030 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
20040 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
20050 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
20060 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
20070 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
20080 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
20090 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
200a0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
200b0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
200c0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
200d0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
200e0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
200f0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
20100 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
20110 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
20120 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
20130 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
20140 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
20150 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
20160 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
20170 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
20180 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
20190 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
201a0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
201b0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
201c0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
201d0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
201e0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
201f0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
20200 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51  errmsg()]..*/.SQ
20210 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
20220 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
20230 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
20240 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
20250 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
20260 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
20270 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
20280 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
20290 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
202a0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
202b0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
202c0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
202d0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
202e0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
202f0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
20300 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
20310 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
20320 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
20330 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
20340 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
20350 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
20360 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
20370 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
20380 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
20390 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
203a0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
203b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
203c0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
203d0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
203e0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
203f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
20400 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
20410 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
20420 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
20430 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
20440 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
20450 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
20460 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
20470 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
20480 6d 6f 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  mon formatting o
20490 70 74 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74  ptions from.** t
204a0 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
204b0 61 72 79 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a  ary printf() .**
204c0 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74   plus some addit
204d0 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61  ional non-standa
204e0 72 64 20 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d  rd formats ([%q]
204f0 2c 20 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e  , [%Q], [%w], an
20500 64 20 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20  d [%z])..** See 
20510 74 68 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72  the [built-in pr
20520 69 6e 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74  intf()] document
20530 61 74 69 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c  ation for detail
20540 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
20550 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
20560 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
20570 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
20580 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
20590 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
205a0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
205b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
205c0 36 34 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  64()]..** The st
205d0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
205e0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
205f0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
20600 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
20610 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
20620 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
20630 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
20640 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
20650 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d  ite3_malloc64()]
20660 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
20670 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
20680 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
20690 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
206a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
206b0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
206c0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
206d0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
206e0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
206f0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
20700 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
20710 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
20720 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
20730 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
20740 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
20750 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
20760 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
20770 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
20780 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
20790 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
207a0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
207b0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
207c0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
207d0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
207e0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
207f0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
20800 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
20810 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
20820 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
20830 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
20840 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
20850 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
20860 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
20870 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
20880 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
20890 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
208a0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
208b0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
208c0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
208d0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
208e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
208f0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
20900 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
20910 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
20920 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
20930 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
20940 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
20950 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
20960 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
20970 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
20980 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
20990 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
209a0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
209b0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
209c0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
209d0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
209e0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
209f0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
20a00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
20a10 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
20a20 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
20a30 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
20a40 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
20a50 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
20a60 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
20a70 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
20a80 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
20a90 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
20aa0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
20ab0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
20ac0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
20ad0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
20ae0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
20af0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
20b00 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
20b10 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
20b20 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62  ** See also:  [b
20b30 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29  uilt-in printf()
20b40 5d 2c 20 5b 70 72 69 6e 74 66 28 29 20 53 51 4c  ], [printf() SQL
20b50 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 53 51   function].*/.SQ
20b60 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
20b70 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
20b80 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
20b90 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
20ba0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
20bb0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
20bc0 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45  va_list);.SQLITE
20bd0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
20be0 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
20bf0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
20c00 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  *, ...);.SQLITE_
20c10 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
20c20 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
20c30 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
20c40 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
20c50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
20c60 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
20c70 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
20c80 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
20c90 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
20ca0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
20cb0 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
20cc0 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
20cd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
20ce0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
20cf0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
20d00 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
20d10 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
20d20 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
20d30 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
20d40 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
20d50 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
20d60 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
20d70 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
20d80 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
20d90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20da0 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
20db0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
20dc0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
20dd0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
20de0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
20df0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
20e00 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
20e10 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
20e20 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
20e30 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
20e40 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
20e50 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
20e60 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
20e70 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
20e80 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
20e90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
20ea0 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
20eb0 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
20ec0 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
20ed0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
20ee0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
20ef0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
20f00 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73  N) routine works
20f10 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71   just like.** sq
20f20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
20f30 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
20f40 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d   an unsigned 64-
20f50 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74  bit integer inst
20f60 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e  ead.** of a sign
20f70 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  ed 32-bit intege
20f80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
20f90 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
20fa0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
20fb0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
20fc0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
20fd0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
20fe0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
20ff0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
21000 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
21010 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
21020 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
21030 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
21040 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
21050 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
21060 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
21070 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
21080 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
21090 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
210a0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
210b0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
210c0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
210d0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
210e0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
210f0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
21100 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
21110 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
21120 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
21130 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
21140 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
21150 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
21160 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
21170 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
21180 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
21190 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
211a0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
211b0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
211c0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
211d0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
211e0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
211f0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
21200 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
21210 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
21220 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
21230 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74  realloc(X,N) int
21240 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
21250 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
21260 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
21270 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61  cation X to be a
21280 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e  t least N bytes.
21290 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61  .** ^If the X pa
212a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
212b0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a  e3_realloc(X,N).
212c0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
212d0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
212e0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
212f0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
21300 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
21310 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  (N)..** ^If the 
21320 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  N parameter to s
21330 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
21340 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  ,N) is zero or.*
21350 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
21360 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
21370 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
21380 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
21390 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a  qlite3_free(X)..
213a0 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
213b0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
213c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
213d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
213e0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
213f0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
21400 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75   or NULL if insu
21410 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
21420 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
21430 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
21440 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
21450 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
21460 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
21470 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
21480 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
21490 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
214a0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
214b0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
214c0 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
214d0 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70  c(X,N) and the p
214e0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
214f0 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
21500 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
21510 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55  (X,N) returns NU
21520 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69  LL and N is posi
21530 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  tive, then the.*
21540 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  * prior allocati
21550 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  on is not freed.
21560 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
21570 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c  te3_realloc64(X,
21580 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  N) interfaces wo
21590 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a  rks the same as.
215a0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
215b0 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74  oc(X,N) except t
215c0 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69  hat N is a 64-bi
215d0 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
215e0 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
215f0 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64   a 32-bit signed
21600 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
21610 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72  ^If X is a memor
21620 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65  y allocation pre
21630 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
21640 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
21650 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
21660 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73  e3_malloc64(), s
21670 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
21680 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  , or sqlite3_rea
21690 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a  lloc64(), then.*
216a0 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
216b0 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  X) returns the s
216c0 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f  ize of that memo
216d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e  ry allocation in
216e0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20   bytes..** ^The 
216f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
21700 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  y sqlite3_msize(
21710 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  X) might be larg
21720 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62  er than the numb
21730 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72  er.** of bytes r
21740 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20  equested when X 
21750 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20  was allocated.  
21760 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20  ^If X is a NULL 
21770 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
21780 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
21790 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20   returns zero.  
217a0 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73  If X points to s
217b0 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73  omething that is
217c0 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69   not.** the begi
217d0 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20  nning of memory 
217e0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69  allocation, or i
217f0 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  f it points to a
21800 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c   formerly.** val
21810 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  id memory alloca
21820 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f  tion that has no
21830 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68  w been freed, th
21840 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
21850 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73  ** of sqlite3_ms
21860 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69  ize(X) is undefi
21870 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ned and possibly
21880 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
21890 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
218a0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
218b0 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65  malloc(), sqlite
218c0 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  3_realloc(),.** 
218d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
218e0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
218f0 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69  realloc64().** i
21900 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
21910 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
21920 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
21930 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
21940 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
21950 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
21960 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
21970 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
21980 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
21990 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
219a0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
219b0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
219c0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
219d0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
219e0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
219f0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
21a00 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
21a10 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
21a20 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
21a30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
21a40 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
21a50 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
21a60 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
21a70 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
21a80 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
21a90 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
21aa0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
21ab0 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
21ac0 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
21ad0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
21ae0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
21af0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
21b00 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
21b10 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
21b20 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
21b30 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
21b40 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
21b50 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
21b60 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
21b70 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
21b80 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
21b90 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
21ba0 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
21bb0 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
21bc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
21bd0 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
21be0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
21bf0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
21c00 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
21c10 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
21c20 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
21c30 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
21c40 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
21c50 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
21c60 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
21c70 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
21c80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
21c90 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
21ca0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
21cb0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
21cc0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
21cd0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
21ce0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
21cf0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
21d00 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
21d10 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
21d20 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
21d30 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
21d40 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
21d50 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
21d60 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
21d70 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
21d80 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
21d90 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
21da0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
21db0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
21dc0 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  c()]..*/.SQLITE_
21dd0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
21de0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53  3_malloc(int);.S
21df0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
21e00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
21e10 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  (sqlite3_uint64)
21e20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
21e30 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
21e40 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
21e50 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
21e60 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
21e70 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
21e80 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
21e90 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
21ea0 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
21eb0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
21ec0 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  e3_uint64 sqlite
21ed0 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a  3_msize(void*);.
21ee0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21ef0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
21f00 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
21f10 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
21f20 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
21f30 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
21f40 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
21f50 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
21f60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
21f70 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
21f80 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
21f90 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
21fa0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
21fb0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
21fc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
21fd0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
21fe0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
21ff0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
22000 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22010 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
22020 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
22030 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
22040 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
22050 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
22060 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
22070 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
22080 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
22090 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
220a0 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
220b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
220c0 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
220d0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
220e0 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
220f0 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
22100 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
22110 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
22120 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
22130 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
22140 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
22150 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
22160 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
22170 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
22180 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
22190 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
221a0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
221b0 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
221c0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
221d0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
221e0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
221f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
22200 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
22210 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
22220 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
22230 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
22240 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
22250 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
22260 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
22270 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
22280 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
22290 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
222a0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
222b0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
222c0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
222d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
222e0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
222f0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
22300 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
22310 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49  e reset..*/.SQLI
22320 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
22330 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
22340 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
22350 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
22360 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
22370 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
22380 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
22390 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
223a0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
223b0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
223c0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
223d0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
223e0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
223f0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
22400 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
22410 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
22420 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
22430 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
22440 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
22450 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
22460 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
22470 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
22480 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
22490 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
224a0 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
224b0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
224c0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
224d0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
224e0 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
224f0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
22500 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
22510 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
22520 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
22530 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
22540 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
22550 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
22560 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
22570 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
22580 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72  P..** ^The P par
22590 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20  ameter can be a 
225a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
225b0 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75  .** ^If this rou
225c0 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65  tine has not bee
225d0 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c  n previously cal
225e0 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72  led or if the pr
225f0 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68  evious.** call h
22600 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f  ad N less than o
22610 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ne or a NULL poi
22620 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e  nter for P, then
22630 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20   the PRNG is.** 
22640 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
22650 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
22660 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
22670 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a  mness method of.
22680 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  ** the default [
22690 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
226a0 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ect..** ^If the 
226b0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
226c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
226d0 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d  d an N of 1 or m
226e0 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e  ore and a.** non
226f0 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65  -NULL P then the
22700 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
22710 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
22720 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
22730 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
22740 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
22750 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
22760 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
22770 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
22780 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
22790 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
227a0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
227b0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
227c0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
227d0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  n Callbacks.** M
227e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
227f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
22800 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22810 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  }.**.** ^This ro
22820 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
22830 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
22840 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
22850 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
22860 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22870 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
22880 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
22890 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
228a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
228b0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
228c0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
228d0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
228e0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
228f0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
22900 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
22910 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
22920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
22930 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c  pare_v3()], [sql
22940 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
22950 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
22960 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20  are16_v2()],.** 
22970 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
22980 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e  pare16_v3()].  ^
22990 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
229a0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
229b0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
229c0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
229d0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
229e0 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
229f0 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
22a00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22a10 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22a20 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
22a30 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
22a40 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
22a50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22a60 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
22a70 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
22a80 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
22a90 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
22aa0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
22ab0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
22ac0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
22ad0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
22ae0 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
22af0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
22b00 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
22b10 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
22b20 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
22b30 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
22b40 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
22b50 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If 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 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
22b80 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
22b90 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
22ba0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
22bb0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
22bc0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
22bd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22be0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
22bf0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
22c00 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
22c10 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
22c20 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
22c30 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
22c40 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
22c50 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
22c60 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
22c70 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
22c80 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
22c90 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
22ca0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
22cb0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
22cc0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
22cd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
22ce0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
22cf0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
22d00 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
22d10 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
22d20 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
22d30 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
22d40 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
22d50 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
22d60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
22d70 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
22d80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
22d90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
22da0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
22db0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
22dc0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
22dd0 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
22de0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
22df0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
22e00 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
22e10 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
22e20 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
22e30 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
22e40 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
22e50 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
22e60 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
22e70 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
22e80 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
22e90 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
22ea0 20 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c   are either NULL
22eb0 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72   pointers or zer
22ec0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
22ed0 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e  ings.** that con
22ee0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  tain additional 
22ef0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
22f00 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
22f10 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70  uthorized..** Ap
22f20 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
22f30 61 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 72  always be prepar
22f40 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20  ed to encounter 
22f50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
22f60 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  n any.** of the 
22f70 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 68  third through th
22f80 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
22f90 72 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72  rs of the author
22fa0 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
22fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
22fc0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
22fd0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
22fe0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
22ff0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
23000 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
23010 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
23020 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
23030 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
23040 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
23050 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
23060 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
23070 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
23080 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
23090 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
230a0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
230b0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
230c0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
230d0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
230e0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
230f0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
23100 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
23110 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
23120 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
23130 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69   ^When a table i
23140 73 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20  s referenced by 
23150 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e  a [SELECT] but n
23160 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20  o column values 
23170 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64  are.** extracted
23180 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65   from that table
23190 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e   (for example in
231a0 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a   a query like.**
231b0 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a   "SELECT count(*
231c0 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65  ) FROM tab") the
231d0 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45  n the [SQLITE_RE
231e0 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63  AD] authorizer c
231f0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e  allback.** is in
23200 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74  voked once for t
23210 68 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61  hat table with a
23220 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61   column name tha
23230 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  t is an empty st
23240 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
23250 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
23260 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
23270 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
23280 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
23290 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
232a0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
232b0 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
232c0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
232d0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
232e0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
232f0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
23300 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
23310 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
23320 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
23330 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
23340 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
23350 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
23360 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
23370 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
23380 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
23390 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
233a0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
233b0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
233c0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
233d0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
233e0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
233f0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
23400 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
23410 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
23420 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
23430 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
23440 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
23450 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
23460 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
23470 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
23480 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
23490 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
234a0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
234b0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
234c0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
234d0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
234e0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
234f0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
23500 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
23510 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
23520 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
23530 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
23540 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
23550 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
23560 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
23570 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
23580 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
23590 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
235a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
235b0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
235c0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
235d0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
235e0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
235f0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
23600 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
23610 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
23620 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
23630 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
23640 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
23650 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
23660 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
23670 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
23680 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
23690 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
236a0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
236b0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
236c0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
236d0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
236e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
236f0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
23700 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
23710 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
23720 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
23730 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
23740 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
23750 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
23760 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
23770 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
23780 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
23790 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
237a0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
237b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
237c0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
237d0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
237e0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
237f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
23800 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
23810 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
23820 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
23830 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
23840 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23850 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
23860 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
23870 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
23880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
23890 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
238a0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
238b0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
238c0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
238d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
238e0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
238f0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
23900 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
23910 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
23920 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
23930 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23940 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
23950 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
23960 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
23970 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
23980 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
23990 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
239a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
239b0 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
239c0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
239d0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
239e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
239f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
23a00 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
23a10 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
23a20 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
23a30 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
23a40 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
23a50 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
23a60 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
23a70 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
23a80 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
23a90 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
23aa0 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
23ab0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
23ac0 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
23ad0 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
23ae0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23af0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
23b00 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
23b10 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
23b20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
23b30 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
23b40 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
23b50 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
23b60 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
23b70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
23b80 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
23b90 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
23ba0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
23bb0 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
23bc0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
23bd0 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
23be0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
23bf0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
23c00 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
23c10 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
23c20 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
23c30 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
23c40 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
23c50 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
23c60 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
23c70 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
23c80 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
23c90 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
23ca0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
23cb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
23cc0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
23cd0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
23ce0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
23cf0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
23d00 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
23d10 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
23d20 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
23d30 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
23d40 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
23d50 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
23d60 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
23d70 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
23d80 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
23d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23da0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
23db0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
23dc0 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
23dd0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
23de0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
23df0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
23e00 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
23e10 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
23e20 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
23e30 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
23e40 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
23e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
23e60 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
23e70 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
23e80 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
23e90 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
23ea0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
23eb0 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
23ec0 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
23ed0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
23ee0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
23ef0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
23f00 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
23f10 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
23f20 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
23f30 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
23f40 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
23f50 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
23f60 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
23f70 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
23f80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
23f90 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
23fa0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
23fb0 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
23fc0 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
23fd0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
23fe0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
23ff0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
24000 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
24010 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
24020 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
24030 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
24040 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
24050 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
24060 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
24070 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
24080 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
24090 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
240a0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
240b0 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
240c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
240d0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
240e0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
240f0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
24100 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
24110 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
24120 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
24130 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
24140 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
24150 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
24160 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
24170 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
24180 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
24190 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
241a0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
241b0 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
241c0 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
241d0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
241e0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
241f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24200 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24210 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
24220 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
24230 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
24240 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
24250 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
24260 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
24270 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
24280 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
24290 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
242a0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
242b0 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
242c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
242d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
242e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
242f0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
24300 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
24310 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
24320 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
24330 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
24340 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
24350 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24360 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
24370 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24380 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
24390 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
243a0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
243b0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
243c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
243d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
243e0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
243f0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
24400 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24410 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24420 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
24430 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
24440 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
24450 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24460 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24470 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
24480 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
24490 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
244a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
244b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
244c0 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
244d0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
244e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
244f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24500 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24510 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
24520 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
24530 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
24540 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24550 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24560 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
24570 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
24580 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
24590 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
245a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
245b0 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
245c0 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
245d0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
245e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
245f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24600 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
24610 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
24620 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
24630 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24640 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24650 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
24660 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
24670 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
24680 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
24690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
246a0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
246b0 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
246c0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
246d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
246e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
246f0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
24700 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
24710 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
24720 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
24730 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
24740 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
24750 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
24760 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
24770 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24780 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
24790 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
247a0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
247b0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
247c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
247d0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
247e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
247f0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
24800 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
24810 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
24820 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
24830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
24840 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24850 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
24860 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
24870 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
24880 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
24890 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
248a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
248b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
248c0 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
248d0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
248e0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
248f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24900 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24910 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
24920 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
24930 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
24940 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
24950 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24960 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
24970 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
24980 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
24990 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
249a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
249b0 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
249c0 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
249d0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
249e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
249f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24a00 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
24a10 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
24a20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
24a30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24a40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24a50 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
24a60 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
24a70 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
24a80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
24a90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24aa0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
24ab0 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
24ac0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
24ad0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24ae0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24af0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
24b00 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
24b10 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
24b20 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
24b30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24b40 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
24b50 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
24b60 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
24b70 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
24b80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
24b90 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
24ba0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
24bb0 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
24bc0 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
24bd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
24be0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
24bf0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
24c00 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
24c10 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
24c20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
24c30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24c40 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
24c50 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
24c60 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
24c70 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
24c80 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
24c90 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24ca0 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
24cb0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
24cc0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
24cd0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
24ce0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
24cf0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
24d00 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65  es are deprecate
24d10 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  d. Use the [sqli
24d20 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
24d30 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73  interface.** ins
24d40 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74  tead of the rout
24d50 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68  ines described h
24d60 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ere..**.** These
24d70 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
24d80 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
24d90 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
24da0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
24db0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
24dc0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
24dd0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
24de0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
24df0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
24e00 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
24e10 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
24e20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
24e30 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
24e40 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
24e50 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
24e60 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
24e70 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
24e80 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
24e90 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
24ea0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
24eb0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
24ec0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
24ed0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
24ee0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
24ef0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
24f00 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
24f10 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
24f20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
24f30 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
24f40 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
24f50 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
24f60 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
24f70 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
24f80 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
24f90 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
24fa0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
24fb0 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
24fc0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
24fd0 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
24fe0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
24ff0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
25000 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
25010 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
25020 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
25030 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
25040 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
25050 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
25060 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
25070 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
25080 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
25090 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
250a0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
250b0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
250c0 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
250d0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
250e0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
250f0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
25100 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
25110 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
25120 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
25130 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
25140 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
25150 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
25160 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
25170 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
25180 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
25190 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
251a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
251b0 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
251c0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
251d0 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
251e0 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
251f0 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
25200 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
25210 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
25220 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
25230 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
25240 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
25250 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
25260 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
25270 6c 6c 62 61 63 6b 2e 20 20 49 6e 76 6f 6b 69 6e  llback.  Invokin
25280 67 0a 2a 2a 20 65 69 74 68 65 72 20 5b 73 71 6c  g.** either [sql
25290 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 6f 72  ite3_trace()] or
252a0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
252b0 76 32 28 29 5d 20 77 69 6c 6c 20 63 61 6e 63 65  v2()] will cance
252c0 6c 20 74 68 65 0a 2a 2a 20 70 72 6f 66 69 6c 65  l the.** profile
252d0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2f 0a 53 51   callback..*/.SQ
252e0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
252f0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
25300 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
25310 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
25320 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
25330 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
25340 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  id*);.SQLITE_API
25350 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
25360 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
25370 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
25380 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
25390 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
253a0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
253b0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
253c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
253d0 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e  : SQL Trace Even
253e0 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
253f0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43  RDS: SQLITE_TRAC
25400 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  E.**.** These co
25410 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79  nstants identify
25420 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e   classes of even
25430 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d  ts that can be m
25440 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e  onitored.** usin
25450 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  g the [sqlite3_t
25460 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69  race_v2()] traci
25470 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d  ng logic.  The M
25480 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
25490 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
254a0 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61  2(D,M,X,P)] is a
254b0 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  n OR-ed combinat
254c0 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ion of one or mo
254d0 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  re of.** the fol
254e0 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
254f0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  .  ^The first ar
25500 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
25510 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
25520 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  is one of the fo
25530 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
25540 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61  s..**.** New tra
25550 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d  cing constants m
25560 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
25570 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
25580 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
25590 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72  allback has four
255a0 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c   arguments: xCal
255b0 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
255c0 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
255d0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
255e0 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f   integer type co
255f0 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54  des above..** ^T
25600 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
25610 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
25620 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70  ontext pointer p
25630 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
25640 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  ** fourth argume
25650 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
25660 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54  race_v2()]..** T
25670 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
25680 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
25690 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
256a0 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
256b0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
256c0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d  LITE_TRACE_STMT]
256d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
256e0 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20  CE_STMT</dt>.** 
256f0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
25700 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61  RACE_STMT callba
25710 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
25720 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74  en a prepared st
25730 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74  atement.** first
25740 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20   begins running 
25750 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20  and possibly at 
25760 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69  other times duri
25770 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74  ng the.** execut
25780 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61  ion of the prepa
25790 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73  red statement, s
257a0 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74  uch as at the st
257b0 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74  art of each.** t
257c0 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
257d0 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  m. ^The P argume
257e0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
257f0 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  to the.** [prepa
25800 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
25810 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20  ^The X argument 
25820 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
25830 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a  a string which.*
25840 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e  * is the unexpan
25850 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20  ded SQL text of 
25860 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
25870 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c  tement or an SQL
25880 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61   comment .** tha
25890 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20  t indicates the 
258a0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20  invocation of a 
258b0 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63  trigger.  ^The c
258c0 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70  allback can comp
258d0 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ute.** the same 
258e0 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20  text that would 
258f0 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e  have been return
25900 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79  ed by the legacy
25910 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
25920 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
25930 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61  by using the X a
25940 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62  rgument when X b
25950 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20  egins with "--" 
25960 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20  and invoking.** 
25970 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  [sqlite3_expande
25980 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77  d_sql(P)] otherw
25990 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ise..**.** [[SQL
259a0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
259b0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
259c0 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74  RACE_PROFILE</dt
259d0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
259e0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
259f0 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69  E callback provi
25a00 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c  des approximatel
25a10 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e  y the same.** in
25a20 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20  formation as is 
25a30 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
25a40 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
25a50 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ()] callback..**
25a60 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
25a70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
25a80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25a90 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
25aa0 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
25ab0 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62  points to a 64-b
25ac0 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  it integer which
25ad0 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65   is the estimate
25ae0 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  d of.** the numb
25af0 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
25b00 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
25b10 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  ed statement too
25b20 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68  k to run..** ^Th
25b30 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
25b40 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
25b50 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
25b60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
25b70 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  nishes..**.** [[
25b80 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
25b90 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
25ba0 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20  ACE_ROW</dt>.** 
25bb0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
25bc0 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63  RACE_ROW callbac
25bd0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
25be0 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64  never a prepared
25bf0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65  .** statement ge
25c00 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65  nerates a single
25c10 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20   row of result. 
25c20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75   .** ^The P argu
25c30 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
25c40 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
25c50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
25c60 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
25c70 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
25c80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
25c90 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e  ACE_CLOSE]] <dt>
25ca0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
25cb0 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SE</dt>.** <dd>^
25cc0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
25cd0 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69  CLOSE callback i
25ce0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
25cf0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
25d00 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
25d10 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
25d20 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
25d30 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
25d40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a   connection] obj
25d50 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58  ect.** and the X
25d60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
25d70 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  sed..** </dl>.*/
25d80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25d90 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20  TRACE_STMT      
25da0 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51   0x01.#define SQ
25db0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
25dc0 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69  LE    0x02.#defi
25dd0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
25de0 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a  ROW        0x04.
25df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
25e00 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20  RACE_CLOSE      
25e10 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x08../*.** CAPI
25e20 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
25e30 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Hook.** METHOD: 
25e40 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
25e50 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
25e60 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74  _v2(D,M,X,P) int
25e70 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
25e80 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63   a trace callbac
25e90 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
25ea0 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73  against [databas
25eb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
25ec0 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20   using property 
25ed0 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f  mask M.** and co
25ee0 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e  ntext pointer P.
25ef0 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c    ^If the X call
25f00 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20  back is.** NULL 
25f10 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b  or if the M mask
25f20 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   is zero, then t
25f30 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c  racing is disabl
25f40 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72  ed.  The.** M ar
25f50 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
25f60 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d   the bitwise OR-
25f70 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
25f80 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  f.** zero or mor
25f90 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
25fa0 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
25fb0 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  * ^Each call to 
25fc0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74  either sqlite3_t
25fd0 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
25fe0 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65  3_trace_v2() ove
25ff0 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63  rrides .** (canc
26000 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63  els) any prior c
26010 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
26020 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
26030 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a  e3_trace_v2()..*
26040 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c  *.** ^The X call
26050 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
26060 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20  whenever any of 
26070 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74  the events ident
26080 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73  ified by .** mas
26090 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65  k M occur.  ^The
260a0 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20   integer return 
260b0 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63  value from the c
260c0 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65  allback is curre
260d0 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c  ntly.** ignored,
260e0 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79   though this may
260f0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
26100 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c  e releases.  Cal
26110 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lback.** impleme
26120 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
26130 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65  return zero to e
26140 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d  nsure future com
26150 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
26160 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
26170 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
26180 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  ith four argumen
26190 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43  ts: callback(T,C
261a0 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
261b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
261c0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
261d0 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61  TRACE].** consta
261e0 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20  nts to indicate 
261f0 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  why the callback
26200 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a   was invoked..**
26210 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74   ^The C argument
26220 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
26230 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  e context pointe
26240 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  r..** The P and 
26250 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
26260 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
26270 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
26280 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  n T..**.** The s
26290 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
262a0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
262b0 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61  ntended to repla
262c0 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ce the legacy.**
262d0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
262e0 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e  ite3_trace()] an
262f0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d [sqlite3_profi
26300 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77  le()], both of w
26310 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72  hich.** are depr
26320 65 63 61 74 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  ecated..*/.SQLIT
26330 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
26340 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71  3_trace_v2(.  sq
26350 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e  lite3*,.  unsign
26360 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28  ed uMask,.  int(
26370 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69  *xCallback)(unsi
26380 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  gned,void*,void*
26390 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20  ,void*),.  void 
263a0 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pCtx.);../*.** 
263b0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
263c0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
263d0 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
263e0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
263f0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
26400 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
26410 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
26420 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
26430 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
26440 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
26450 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
26460 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
26470 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
26480 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
26490 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
264a0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
264b0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
264c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
264d0 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
264e0 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
264f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
26500 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
26510 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
26520 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
26530 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
26540 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
26550 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
26560 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
26570 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
26580 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
26590 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
265a0 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
265b0 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
265c0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
265d0 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
265e0 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
265f0 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
26600 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
26610 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
26620 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
26630 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
26640 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
26650 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
26660 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
26670 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
26680 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
26690 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
266a0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
266b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
266c0 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
266d0 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
266e0 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
266f0 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
26700 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
26710 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
26720 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
26730 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
26740 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
26750 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
26760 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
26770 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
26780 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
26790 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
267a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
267b0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
267c0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
267d0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
267e0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
267f0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
26800 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
26810 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
26820 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
26830 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
26840 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
26850 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
26860 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
26870 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
26880 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
26890 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
268a0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
268b0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
268c0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
268d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
268e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
268f0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
26900 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
26910 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26920 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
26930 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
26940 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
26950 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .**.*/.SQLITE_AP
26960 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  I void sqlite3_p
26970 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
26980 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
26990 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
269a0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
269b0 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
269c0 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
269d0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53  nnection.** CONS
269e0 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
269f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
26a00 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
26a10 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
26a20 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
26a30 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
26a40 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
26a50 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
26a60 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
26a70 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
26a80 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
26a90 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
26aa0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
26ab0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
26ac0 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
26ad0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
26ae0 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
26af0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26b00 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
26b10 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
26b20 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
26b30 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
26b40 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
26b50 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
26b60 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
26b70 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
26b80 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
26b90 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
26ba0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
26bb0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
26bc0 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
26bd0 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
26be0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
26bf0 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
26c00 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
26c10 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
26c20 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
26c30 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
26c40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
26c50 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
26c60 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
26c70 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
26c80 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
26c90 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
26ca0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
26cb0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
26cc0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
26cd0 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
26ce0 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
26cf0 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
26d00 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
26d10 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
26d20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
26d30 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
26d40 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
26d50 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
26d60 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
26d70 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
26d80 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
26d90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
26da0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
26db0 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
26dc0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
26dd0 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
26de0 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
26df0 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
26e00 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
26e10 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
26e20 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
26e30 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
26e40 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
26e50 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
26e60 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
26e70 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
26e80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26e90 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
26ea0 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
26eb0 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
26ec0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
26ed0 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
26ee0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
26ef0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
26f00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
26f10 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
26f20 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
26f30 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
26f40 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
26f50 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
26f60 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
26f70 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
26f80 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
26f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26fa0 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
26fb0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
26fc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26fd0 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
26fe0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
26ff0 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
27000 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
27010 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
27020 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
27030 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
27040 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
27050 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
27060 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
27070 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
27080 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
27090 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
270a0 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
270b0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
270c0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
270d0 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
270e0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
270f0 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
27100 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
27110 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
27120 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
27130 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
27140 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
27150 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
27160 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
27170 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
27180 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
27190 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
271a0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
271b0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
271c0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
271d0 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
271e0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
271f0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
27200 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
27210 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
27220 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
27230 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
27240 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
27250 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
27260 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
27270 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
27280 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
27290 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
272a0 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
272b0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
272c0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
272d0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
272e0 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
272f0 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
27300 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
27310 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
27320 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
27330 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
27340 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
27350 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
27360 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
27370 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
27380 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
27390 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
273a0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
273b0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
273c0 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
273d0 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
273e0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
273f0 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
27400 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
27410 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
27420 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
27430 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
27440 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
27450 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
27460 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
27470 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
27480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27490 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
274a0 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
274b0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
274c0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
274d0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
274e0 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
274f0 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
27500 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
27510 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
27520 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
27530 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
27540 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
27550 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27560 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
27570 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
27580 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
27590 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
275a0 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
275b0 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
275c0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
275d0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
275e0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
275f0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
27600 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
27610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27620 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
27630 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
27640 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
27650 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
27660 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
27670 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
27680 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
27690 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
276a0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
276b0 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
276c0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
276d0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
276e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
276f0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
27700 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
27710 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
27720 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
27730 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
27740 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
27750 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27760 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
27770 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
27780 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
27790 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
277a0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
277b0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
277c0 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
277d0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
277e0 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
277f0 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
27800 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
27810 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
27820 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
27830 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
27840 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
27850 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
27860 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
27870 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
27880 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
27890 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
278a0 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
278b0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
278c0 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
278d0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
278e0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
278f0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
27900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
27910 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
27920 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
27930 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
27940 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
27950 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
27960 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
27970 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
27980 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
27990 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
279a0 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
279b0 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
279c0 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
279d0 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
279e0 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
279f0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
27a00 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
27a10 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
27a20 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
27a30 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
27a40 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
27a50 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
27a60 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
27a70 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
27a80 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
27a90 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
27aa0 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
27ab0 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
27ac0 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
27ad0 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
27ae0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
27af0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27b00 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
27b10 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
27b20 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
27b30 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
27b40 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
27b50 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
27b60 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
27b70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
27b80 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
27b90 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
27ba0 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
27bb0 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
27bc0 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
27bd0 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
27be0 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
27bf0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
27c00 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
27c10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
27c20 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
27c30 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72   in the third ar
27c40 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
27c50 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
27c60 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
27c70 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
27c80 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
27c90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
27ca0 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
27cb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
27cc0 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
27cd0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
27ce0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
27cf0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
27d00 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
27d10 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
27d20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
27d30 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
27d40 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
27d50 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
27d60 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
27d70 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
27d80 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
27d90 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
27da0 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
27db0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
27dc0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
27dd0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
27de0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
27df0 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
27e00 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
27e10 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
27e20 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
27e30 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
27e40 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
27e50 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
27e60 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
27e70 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
27e80 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
27e90 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
27ea0 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
27eb0 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
27ec0 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
27ed0 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
27ee0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
27ef0 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
27f00 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
27f10 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
27f20 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
27f30 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
27f40 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
27f50 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
27f60 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
27f70 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
27f80 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
27f90 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
27fa0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
27fb0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
27fc0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
27fd0 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
27fe0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
27ff0 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
28000 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
28010 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
28020 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
28030 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
28040 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
28050 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
28060 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
28070 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
28080 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
28090 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
280a0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
280b0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
280c0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
280d0 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
280e0 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
280f0 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
28100 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
28110 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
28120 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
28130 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
28140 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
28150 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
28160 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
28170 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
28180 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
28190 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
281a0 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
281b0 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
281c0 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
281d0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
281e0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
281f0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
28200 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
28210 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
28220 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
28230 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
28240 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
28250 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
28260 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
28270 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
28280 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
28290 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
282a0 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
282b0 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
282c0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
282d0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
282e0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
282f0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
28300 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
28310 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
28320 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
28330 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
28340 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
28350 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
28360 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
28370 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
28380 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
28390 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
283a0 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
283b0 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
283c0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
283d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
283e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
283f0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
28400 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
28410 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
28420 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
28430 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
28440 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
28450 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
28460 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
28470 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
28480 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
28490 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
284a0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
284b0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
284c0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
284d0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
284e0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
284f0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
28500 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
28510 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
28520 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
28530 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
28540 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
28550 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
28560 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
28570 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
28580 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
28590 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
285a0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
285b0 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
285c0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
285d0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
285e0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
285f0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
28600 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
28610 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
28620 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
28630 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
28640 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
28650 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
28660 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
28670 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
28680 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
28690 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
286a0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
286b0 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
286c0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
286d0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
286e0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
286f0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
28700 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
28710 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
28720 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
28730 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
28740 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
28750 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
28760 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
28770 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
28780 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
28790 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
287a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
287b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
287c0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
287d0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
287e0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
287f0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
28800 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
28810 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
28820 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
28830 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
28840 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
28850 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
28860 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
28870 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
28880 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
28890 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
288a0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
288b0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
288c0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
288d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
288e0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
288f0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
28900 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
28910 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
28920 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
28930 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
28940 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
28950 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
28960 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
28970 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
28980 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
28990 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
289a0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
289b0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
289c0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
289d0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
289e0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
289f0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
28a00 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
28a10 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
28a20 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
28a30 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
28a40 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
28a50 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
28a60 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
28a70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
28a80 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
28a90 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
28aa0 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
28ab0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28ac0 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
28ad0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
28ae0 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
28af0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
28b00 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
28b10 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
28b20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
28b30 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
28b40 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
28b50 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
28b60 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
28b70 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
28b80 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
28b90 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
28ba0 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
28bb0 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
28bc0 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
28bd0 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
28be0 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
28bf0 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
28c00 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
28c10 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
28c20 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
28c30 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
28c40 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
28c50 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
28c60 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
28c70 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
28c80 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
28c90 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
28ca0 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
28cb0 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
28cc0 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
28cd0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
28ce0 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
28cf0 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
28d00 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
28d10 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
28d20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
28d30 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
28d40 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
28d50 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
28d60 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
28d70 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
28d80 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
28d90 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
28da0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
28db0 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
28dc0 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
28dd0 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
28de0 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
28df0 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
28e00 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
28e10 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
28e20 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
28e30 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
28e40 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
28e50 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
28e60 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
28e70 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
28e80 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
28e90 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
28ea0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
28eb0 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
28ec0 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
28ed0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
28ee0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
28ef0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
28f00 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
28f10 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
28f20 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
28f30 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
28f40 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
28f50 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
28f60 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
28f70 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
28f80 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
28f90 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
28fa0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
28fb0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
28fc0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
28fd0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
28fe0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
28ff0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
29000 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
29010 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
29020 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
29030 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
29040 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
29050 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
29060 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
29070 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
29080 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
29090 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
290a0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
290b0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
290c0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
290d0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
290e0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
290f0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
29100 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
29110 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
29120 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
29130 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
29140 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
29150 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
29160 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
29170 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
29180 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
29190 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
291a0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
291b0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
291c0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
291d0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
291e0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
291f0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
29200 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
29210 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
29220 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
29230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
29240 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
29250 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
29260 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
29270 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
29280 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
29290 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
292a0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
292b0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
292c0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
292d0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
292e0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
292f0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
29300 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
29310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
29320 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
29330 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
29340 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
29350 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
29360 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
29370 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
29380 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
29390 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
293a0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
293b0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
293c0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
293d0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
293e0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
293f0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
29400 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
29410 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
29420 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
29430 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
29440 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
29450 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
29460 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
29470 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
29480 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
29490 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
294a0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
294b0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
294c0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
294d0 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
294e0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
294f0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
29500 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
29510 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
29520 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
29530 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
29540 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
29550 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
29560 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
29570 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
29580 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
29590 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
295a0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
295b0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
295c0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
295d0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
295e0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
295f0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
29600 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
29610 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
29620 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
29630 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
29640 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
29650 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
29660 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
29670 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
29680 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
29690 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
296a0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
296b0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
296c0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
296d0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
296e0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
296f0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
29700 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
29710 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
29720 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
29730 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
29740 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
29750 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
29760 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
29770 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
29780 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
29790 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
297a0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
297b0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
297c0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
297d0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
297e0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
297f0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
29800 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
29810 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
29820 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
29830 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
29840 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
29850 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
29860 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
29870 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
29880 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
29890 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
298a0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
298b0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
298c0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
298d0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
298e0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
298f0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
29900 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
29910 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
29920 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
29930 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
29940 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
29950 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
29960 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
29970 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
29980 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
29990 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
299a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
299b0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
299c0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
299d0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
299e0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
299f0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
29a00 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
29a10 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
29a20 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53  _directory].*/.S
29a30 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
29a40 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
29a50 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
29a60 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
29a70 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
29a80 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
29a90 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
29aa0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
29ab0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
29ac0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
29ad0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
29ae0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
29af0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
29b00 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
29b10 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
29b20 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
29b30 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
29b40 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
29b50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
29b60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
29b70 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
29b80 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
29b90 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
29ba0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
29bb0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
29bc0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
29bd0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
29be0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
29bf0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
29c00 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
29c10 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
29c20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
29c30 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
29c40 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
29c50 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
29c60 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
29c70 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
29c80 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
29c90 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
29ca0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
29cb0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
29cc0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
29cd0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
29ce0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
29cf0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
29d00 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
29d10 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
29d20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
29d30 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
29d40 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
29d50 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
29d60 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
29d70 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
29d80 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
29d90 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
29da0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
29db0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
29dc0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
29dd0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
29de0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
29df0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
29e00 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
29e10 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
29e20 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
29e30 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
29e40 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
29e50 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
29e60 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
29e70 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
29e80 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
29e90 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
29ea0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
29eb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
29ec0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
29ed0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
29ee0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
29ef0 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
29f00 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
29f10 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
29f20 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
29f30 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
29f40 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
29f50 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
29f60 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
29f70 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
29f80 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
29f90 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
29fa0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
29fb0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
29fc0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
29fd0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
29fe0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
29ff0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
2a000 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
2a010 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
2a020 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
2a030 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
2a040 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
2a050 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
2a060 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
2a070 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
2a080 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
2a090 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
2a0a0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
2a0b0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
2a0c0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
2a0d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
2a0e0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
2a0f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
2a100 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
2a110 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
2a120 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
2a130 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
2a140 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
2a150 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
2a160 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
2a170 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
2a180 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
2a190 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
2a1a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
2a1b0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
2a1c0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
2a1d0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
2a1e0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
2a1f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
2a200 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
2a210 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
2a220 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2a230 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
2a240 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
2a250 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
2a260 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
2a270 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2a280 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
2a290 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
2a2a0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
2a2b0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
2a2c0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
2a2d0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
2a2e0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
2a2f0 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
2a300 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
2a310 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
2a320 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
2a330 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
2a340 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
2a350 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
2a360 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
2a370 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
2a380 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
2a390 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
2a3a0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
2a3b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
2a3c0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
2a3d0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
2a3e0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
2a3f0 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
2a400 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2a410 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
2a420 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2a430 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
2a440 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
2a450 20 53 65 65 20 74 68 65 20 5b 55 52 49 20 66 69   See the [URI fi
2a460 6c 65 6e 61 6d 65 5d 20 64 6f 63 75 6d 65 6e 74  lename] document
2a470 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2a480 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2a490 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2a4a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a4b0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
2a4c0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
2a4d0 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
2a4e0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51  har *zParam);.SQ
2a4f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a500 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
2a510 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
2a520 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
2a530 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
2a540 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ault);.SQLITE_AP
2a550 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
2a560 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
2a570 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
2a580 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
2a590 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
2a5a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
2a5b0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
2a5c0 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
2a5d0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
2a5e0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2a5f0 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
2a600 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
2a610 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
2a620 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2a630 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
2a640 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
2a650 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
2a660 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
2a670 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
2a680 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
2a690 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
2a6a0 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
2a6b0 63 61 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  call..** ^The sq
2a6c0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
2a6d0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
2a6e0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
2a6f0 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
2a700 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2a710 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
2a720 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
2a730 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
2a740 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
2a750 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
2a760 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73  **.** The values
2a770 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2a780 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 61  ite3_errcode() a
2a790 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2a7a0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
2a7b0 65 28 29 20 6d 69 67 68 74 20 63 68 61 6e 67 65  e() might change
2a7c0 20 77 69 74 68 20 65 61 63 68 20 41 50 49 20 63   with each API c
2a7d0 61 6c 6c 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20  all..** Except, 
2a7e0 74 68 65 72 65 20 61 72 65 20 73 6f 6d 65 20 69  there are some i
2a7f0 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
2a800 72 65 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  re guaranteed to
2a810 20 6e 65 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65   never.** change
2a820 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2a830 65 20 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 54  e error code.  T
2a840 68 65 20 65 72 72 6f 72 2d 63 6f 64 65 20 70 72  he error-code pr
2a850 65 73 65 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65  eserving.** inte
2a860 72 66 61 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a  rfaces are:.**.*
2a870 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73  * <ul>.** <li> s
2a880 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
2a890 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33  .** <li> sqlite3
2a8a0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
2a8b0 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  e().** <li> sqli
2a8c0 74 65 33 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20  te3_errmsg().** 
2a8d0 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72  <li> sqlite3_err
2a8e0 6d 73 67 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e  msg16().** </ul>
2a8f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a900 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
2a910 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
2a920 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
2a930 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
2a940 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
2a950 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
2a960 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
2a970 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
2a980 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
2a990 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
2a9a0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
2a9b0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
2a9c0 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
2a9d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
2a9e0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
2a9f0 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
2aa00 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
2aa10 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
2aa20 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
2aa30 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
2aa40 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
2aa50 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
2aa60 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
2aa70 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
2aa80 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
2aa90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2aaa0 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
2aab0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
2aac0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
2aad0 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
2aae0 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
2aaf0 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
2ab00 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
2ab10 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
2ab20 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
2ab30 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
2ab40 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
2ab50 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
2ab60 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
2ab70 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
2ab80 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
2ab90 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
2aba0 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
2abb0 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
2abc0 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
2abd0 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
2abe0 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
2abf0 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
2ac00 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
2ac10 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
2ac20 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
2ac30 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
2ac40 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
2ac50 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
2ac60 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
2ac70 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
2ac80 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
2ac90 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
2aca0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2acb0 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
2acc0 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
2acd0 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
2ace0 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
2acf0 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
2ad00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
2ad10 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
2ad20 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
2ad30 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
2ad40 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
2ad50 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
2ad60 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
2ad70 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
2ad80 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
2ad90 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
2ada0 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
2adb0 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
2adc0 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
2add0 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
2ade0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
2adf0 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
2ae00 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
2ae10 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
2ae20 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
2ae30 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
2ae40 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
2ae50 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
2ae60 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
2ae70 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
2ae80 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
2ae90 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
2aea0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2aeb0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2aec0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51  sqlite3 *db);.SQ
2aed0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2aee0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
2aef0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
2af00 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  b);.SQLITE_API c
2af10 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2af20 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
2af30 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
2af40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2af50 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
2af60 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
2af70 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2af80 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
2af90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2afa0 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
2afb0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2afc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
2afd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
2afe0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
2aff0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
2b000 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
2b010 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
2b020 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
2b030 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
2b040 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
2b050 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
2b060 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
2b070 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
2b080 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
2b090 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
2b0a0 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
2b0b0 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
2b0c0 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
2b0d0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
2b0e0 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
2b0f0 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
2b100 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
2b110 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
2b120 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
2b130 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
2b140 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
2b150 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
2b160 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
2b170 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
2b180 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
2b190 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
2b1a0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
2b1b0 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
2b1c0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
2b1d0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
2b1e0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2b1f0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
2b200 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2b210 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
2b220 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
2b230 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
2b240 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2b250 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
2b260 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
2b270 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
2b280 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
2b290 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2b2a0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2b2b0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
2b2c0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2b2d0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
2b2e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2b2f0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
2b300 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
2b310 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
2b320 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
2b330 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
2b340 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
2b350 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b360 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
2b370 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2b380 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
2b390 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
2b3a0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
2b3b0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
2b3c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
2b3d0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
2b3e0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
2b3f0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
2b400 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
2b410 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
2b420 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
2b430 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
2b440 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
2b450 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
2b460 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b470 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
2b480 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
2b490 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
2b4a0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
2b4b0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
2b4c0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
2b4d0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
2b4e0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
2b4f0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
2b500 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
2b510 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2b520 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
2b530 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
2b540 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
2b550 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
2b560 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
2b570 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
2b580 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
2b590 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
2b5a0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
2b5b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
2b5c0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
2b5d0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
2b5e0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
2b5f0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
2b600 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
2b610 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
2b620 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
2b630 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
2b640 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
2b650 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
2b660 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
2b670 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
2b680 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
2b690 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
2b6a0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
2b6b0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
2b6c0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
2b6d0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
2b6e0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
2b6f0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
2b700 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
2b710 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2b720 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
2b730 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
2b740 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
2b750 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b760 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
2b770 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
2b780 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
2b790 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
2b7a0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
2b7b0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
2b7c0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
2b7d0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
2b7e0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
2b7f0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
2b800 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
2b810 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
2b820 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2b830 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
2b840 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
2b850 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
2b860 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
2b870 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
2b880 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
2b890 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
2b8a0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
2b8b0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
2b8c0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
2b8d0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
2b8e0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
2b8f0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
2b900 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
2b910 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
2b920 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
2b930 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
2b940 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
2b950 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
2b960 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
2b970 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
2b980 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
2b990 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
2b9a0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
2b9b0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
2b9c0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
2b9d0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
2b9e0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
2b9f0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
2ba00 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
2ba10 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
2ba20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
2ba30 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
2ba40 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
2ba50 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
2ba60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
2ba70 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
2ba80 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
2ba90 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
2baa0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
2bab0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
2bac0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
2bad0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
2bae0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
2baf0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
2bb00 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
2bb10 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
2bb20 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
2bb30 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
2bb40 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
2bb50 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
2bb60 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
2bb70 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2bb80 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
2bb90 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
2bba0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
2bbb0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
2bbc0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
2bbd0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2bbe0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
2bbf0 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
2bc00 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
2bc10 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
2bc20 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
2bc30 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
2bc40 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
2bc50 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
2bc60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
2bc70 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
2bc80 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
2bc90 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
2bca0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
2bcb0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
2bcc0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
2bcd0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
2bce0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
2bcf0 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
2bd00 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
2bd10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2bd20 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
2bd30 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
2bd40 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2bd50 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
2bd60 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
2bd70 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
2bd80 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
2bd90 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2bda0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
2bdb0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
2bdc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
2bdd0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2bde0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
2bdf0 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
2be00 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
2be10 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
2be20 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2be30 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
2be40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2be50 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
2be60 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2be70 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2be80 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
2be90 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
2bea0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
2beb0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
2bec0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2bed0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
2bee0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
2bef0 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
2bf00 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
2bf10 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2bf20 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2bf30 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2bf40 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2bf50 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
2bf60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
2bf70 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
2bf80 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
2bf90 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
2bfa0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2bfb0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2bfc0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
2bfd0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2bfe0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
2bff0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2c000 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
2c010 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
2c020 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
2c030 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2c040 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
2c050 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
2c060 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2c070 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
2c080 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2c090 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
2c0a0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
2c0b0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
2c0c0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
2c0d0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
2c0e0 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74  ment.  If [sqlit
2c0f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c100 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76   or.** the equiv
2c110 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61  alent tries to a
2c120 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f  llocate space fo
2c130 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73  r more than this
2c140 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a   many opcodes.**
2c150 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65   in a single pre
2c160 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
2c170 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d   an SQLITE_NOMEM
2c180 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2c190 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
2c1a0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2c1b0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
2c1c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2c1d0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
2c1e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2c1f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2c200 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
2c210 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
2c220 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2c230 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
2c240 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2c250 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
2c260 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2c270 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
2c280 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
2c290 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
2c2a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
2c2b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
2c2c0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
2c2d0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
2c2e0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2c2f0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
2c300 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2c310 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
2c320 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
2c330 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
2c340 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
2c350 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
2c360 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2c370 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2c380 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
2c390 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2c3a0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
2c3b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2c3c0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
2c3d0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
2c3e0 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
2c3f0 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
2c400 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
2c410 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
2c420 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2c430 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
2c440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2c450 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
2c460 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
2c470 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
2c480 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2c490 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2c4a0 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
2c4b0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2c4c0 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
2c4d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2c4e0 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
2c4f0 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
2c500 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
2c510 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2c520 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
2c530 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
2c540 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
2c550 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2c560 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2c570 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
2c580 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
2c590 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
2c5a0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
2c5b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
2c5c0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
2c5d0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2c5e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
2c5f0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
2c600 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
2c610 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2c620 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
2c630 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
2c640 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2c650 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
2c660 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
2c670 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2c680 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
2c690 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
2c6a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2c6b0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
2c6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
2c6d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2c6e0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2c6f0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
2c700 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2c710 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2c720 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
2c730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c740 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2c750 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
2c760 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2c770 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
2c780 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
2c790 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
2c7a0 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67  EF: Prepare Flag
2c7b0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
2c7c0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
2c7d0 61 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61  arious flags tha
2c7e0 74 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  t can be passed 
2c7f0 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61  into.** "prepFla
2c800 67 73 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66  gs" parameter of
2c810 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
2c820 65 70 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a  epare_v3()] and.
2c830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2c840 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65  are16_v3()] inte
2c850 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  rfaces..**.** Ne
2c860 77 20 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61  w flags may be a
2c870 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
2c880 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
2c890 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  e..**.** <dl>.**
2c8a0 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52   [[SQLITE_PREPAR
2c8b0 45 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e  E_PERSISTENT]] ^
2c8c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50  (<dt>SQLITE_PREP
2c8d0 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f  ARE_PERSISTENT</
2c8e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53  dt>.** <dd>The S
2c8f0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2c900 52 53 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73  RSISTENT flag is
2c910 20 61 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71   a hint to the q
2c920 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20  uery planner.** 
2c930 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
2c940 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  d statement will
2c950 20 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72   be retained for
2c960 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64   a long time and
2c970 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75  .** probably reu
2c980 73 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29  sed many times.)
2c990 5e 20 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20  ^ ^Without this 
2c9a0 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70  flag, [sqlite3_p
2c9b0 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20  repare_v3()].** 
2c9c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2c9d0 70 61 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73  pare16_v3()] ass
2c9e0 75 6d 65 20 74 68 61 74 20 74 68 65 20 70 72 65  ume that the pre
2c9f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ca00 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64  will .** be used
2ca10 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74   just once or at
2ca20 20 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65   most a few time
2ca30 73 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72  s and then destr
2ca40 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  oyed using.** [s
2ca50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ca60 29 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f  )] relatively so
2ca70 6f 6e 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20  on. The current 
2ca80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61  implementation a
2ca90 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68  cts.** on this h
2caa0 69 6e 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20  int by avoiding 
2cab0 74 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b  the use of [look
2cac0 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f  aside memory] so
2cad0 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65   as not to.** de
2cae0 70 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65  plete the limite
2caf0 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61  d store of looka
2cb00 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74  side memory. Fut
2cb10 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a  ure versions of.
2cb20 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63  ** SQLite may ac
2cb30 74 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64  t on this hint d
2cb40 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a  ifferently..**.*
2cb50 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41  * [[SQLITE_PREPA
2cb60 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45 5d 5d 20 3c  RE_NORMALIZE]] <
2cb70 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52  dt>SQLITE_PREPAR
2cb80 45 5f 4e 4f 52 4d 41 4c 49 5a 45 3c 2f 64 74 3e  E_NORMALIZE</dt>
2cb90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
2cba0 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41  TE_PREPARE_NORMA
2cbb0 4c 49 5a 45 20 66 6c 61 67 20 69 73 20 61 20 6e  LIZE flag is a n
2cbc0 6f 2d 6f 70 2e 20 54 68 69 73 20 66 6c 61 67 20  o-op. This flag 
2cbd0 75 73 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  used.** to be re
2cbe0 71 75 69 72 65 64 20 66 6f 72 20 61 6e 79 20 70  quired for any p
2cbf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cc00 74 20 74 68 61 74 20 77 61 6e 74 65 64 20 74 6f  t that wanted to
2cc10 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   use the.** [sql
2cc20 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f  ite3_normalized_
2cc30 73 71 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  sql()] interface
2cc40 2e 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65 0a  .  However, the.
2cc50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 6f 72 6d  ** [sqlite3_norm
2cc60 61 6c 69 7a 65 64 5f 73 71 6c 28 29 5d 20 69 6e  alized_sql()] in
2cc70 74 65 72 66 61 63 65 20 69 73 20 6e 6f 77 20 61  terface is now a
2cc80 76 61 69 6c 61 62 6c 65 20 74 6f 20 61 6c 6c 0a  vailable to all.
2cc90 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
2cca0 65 6d 65 6e 74 73 2c 20 72 65 67 61 72 64 6c 65  ements, regardle
2ccb0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
2ccc0 20 6e 6f 74 20 74 68 65 79 20 75 73 65 20 74 68   not they use th
2ccd0 69 73 0a 2a 2a 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  is.** flag..**.*
2cce0 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41  * [[SQLITE_PREPA
2ccf0 52 45 5f 4e 4f 5f 56 54 41 42 5d 5d 20 3c 64 74  RE_NO_VTAB]] <dt
2cd00 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  >SQLITE_PREPARE_
2cd10 4e 4f 5f 56 54 41 42 3c 2f 64 74 3e 0a 2a 2a 20  NO_VTAB</dt>.** 
2cd20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50  <dd>The SQLITE_P
2cd30 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 20 66  REPARE_NO_VTAB f
2cd40 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 53  lag causes the S
2cd50 51 4c 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74  QL compiler.** t
2cd60 6f 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  o return an erro
2cd70 72 20 28 65 72 72 6f 72 20 63 6f 64 65 20 53 51  r (error code SQ
2cd80 4c 49 54 45 5f 45 52 52 4f 52 29 20 69 66 20 74  LITE_ERROR) if t
2cd90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 65  he statement use
2cda0 73 0a 2a 2a 20 61 6e 79 20 76 69 72 74 75 61 6c  s.** any virtual
2cdb0 20 74 61 62 6c 65 73 2e 0a 2a 2a 20 3c 2f 64 6c   tables..** </dl
2cdc0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
2cdd0 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2cde0 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 20 20  ISTENT          
2cdf0 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65      0x01.#define
2ce00 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2ce10 4e 4f 52 4d 41 4c 49 5a 45 20 20 20 20 20 20 20  NORMALIZE       
2ce20 20 20 20 20 20 20 20 20 30 78 30 32 0a 23 64 65          0x02.#de
2ce30 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50  fine SQLITE_PREP
2ce40 41 52 45 5f 4e 4f 5f 56 54 41 42 20 20 20 20 20  ARE_NO_VTAB     
2ce50 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 34              0x04
2ce60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ce70 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
2ce80 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2ce90 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
2cea0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
2ceb0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
2cec0 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
2ced0 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
2cee0 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
2cef0 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ute an SQL state
2cf00 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69  ment, it must fi
2cf10 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
2cf20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
2cf30 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
2cf40 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
2cf50 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e  outines.  Or, in
2cf60 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2cf70 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2cf80 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  are constructors
2cf90 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2cfa0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
2cfb0 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ject..**.** The 
2cfc0 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e  preferred routin
2cfd0 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c  e to use is [sql
2cfe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2cff0 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  )].  The.** [sql
2d000 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2d010 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65 67  interface is leg
2d020 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62  acy and should b
2d030 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73  e avoided..** [s
2d040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d050 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72  3()] has an extr
2d060 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70  a "prepFlags" op
2d070 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65  tion that is use
2d080 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c  d.** for special
2d090 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
2d0a0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2d0b0 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73  UTF-8 interfaces
2d0c0 20 69 73 20 70 72 65 66 65 72 72 65 64 2c 20 61   is preferred, a
2d0d0 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74  s SQLite current
2d0e0 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70  ly.** does all p
2d0f0 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46  arsing using UTF
2d100 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20  -8.  The UTF-16 
2d110 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
2d120 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20  rovided.** as a 
2d130 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68  convenience.  Th
2d140 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61  e UTF-16 interfa
2d150 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76  ces work by conv
2d160 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e  erting the.** in
2d170 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54  put text into UT
2d180 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69  F-8, then invoki
2d190 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ng the correspon
2d1a0 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72  ding UTF-8 inter
2d1b0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
2d1c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
2d1d0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
2d1e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2d1f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
2d200 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
2d210 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2d220 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2d230 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2d240 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2d250 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
2d260 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d270 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
2d280 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
2d290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2d2a0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
2d2b0 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
2d2c0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2d2d0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
2d2e0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
2d2f0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
2d300 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2d310 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2d320 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  re_v2(),.** and 
2d330 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d340 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v3().** interfac
2d350 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
2d360 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2d370 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  e16(), sqlite3_p
2d380 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2d390 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2d3a0 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 73 65  epare16_v3() use
2d3b0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
2d3c0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
2d3d0 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
2d3e0 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
2d3f0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
2d400 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
2d410 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
2d420 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
2d430 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
2d440 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2d450 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
2d460 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
2d470 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
2d480 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2d490 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
2d4a0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
2d4b0 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
2d4c0 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
2d4d0 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
2d4e0 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
2d4f0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
2d500 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
2d510 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
2d520 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
2d530 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
2d540 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d550 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
2d560 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
2d570 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
2d580 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
2d590 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
2d5a0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
2d5b0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
2d5c0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
2d5d0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
2d5e0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
2d5f0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
2d600 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
2d610 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2d620 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
2d630 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
2d640 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
2d650 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
2d660 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
2d670 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
2d680 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
2d690 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
2d6a0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
2d6b0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
2d6c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
2d6d0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
2d6e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2d6f0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
2d700 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
2d710 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
2d720 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
2d730 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
2d740 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
2d750 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
2d760 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
2d770 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
2d780 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
2d790 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
2d7a0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
2d7b0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
2d7c0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
2d7d0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
2d7e0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
2d7f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2d800 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
2d810 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
2d820 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
2d830 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
2d840 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
2d850 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
2d860 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2d870 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
2d880 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2d890 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
2d8a0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
2d8b0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2d8c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2d8d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c  e3_prepare_v2(),
2d8e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d8f0 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  _v3(), sqlite3_p
2d900 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2d910 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2d920 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74  epare16_v3() int
2d930 65 72 66 61 63 65 73 20 61 72 65 20 72 65 63 6f  erfaces are reco
2d940 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
2d950 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a  new programs..**
2d960 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72   The older inter
2d970 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70  faces (sqlite3_p
2d980 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
2d990 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2d9a0 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65  ).** are retaine
2d9b0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
2d9c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
2d9d0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
2d9e0 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
2d9f0 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74  ^In the "vX" int
2da00 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
2da10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2da20 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
2da30 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
2da40 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
2da50 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
2da60 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
2da70 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
2da80 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
2da90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
2daa0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
2dab0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
2dac0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
2dad0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2dae0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
2daf0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
2db00 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
2db10 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
2db20 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
2db30 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
2db40 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
2db50 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
2db60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2db70 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
2db80 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2db90 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
2dba0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
2dbb0 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
2dbc0 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
2dbd0 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
2dbe0 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
2dbf0 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
2dc00 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
2dc10 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
2dc20 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
2dc30 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2dc40 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2dc50 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
2dc60 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
2dc70 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
2dc80 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
2dc90 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
2dca0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
2dcb0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
2dcc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2dcd0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
2dce0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
2dcf0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
2dd00 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
2dd10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2dd20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
2dd30 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
2dd40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2dd50 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
2dd60 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
2dd70 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
2dd80 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
2dd90 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
2dda0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
2ddb0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
2ddc0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
2ddd0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
2dde0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
2ddf0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2de00 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2de10 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
2de20 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
2de30 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
2de40 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
2de50 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
2de60 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2de70 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2de80 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
2de90 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
2dea0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
2deb0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
2dec0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
2ded0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
2dee0 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
2def0 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
2df00 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
2df10 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
2df20 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
2df30 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
2df40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
2df50 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
2df60 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
2df70 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
2df80 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
2df90 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
2dfa0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
2dfb0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
2dfc0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2dfd0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2dfe0 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
2dff0 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
2e000 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
2e010 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
2e020 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2e030 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
2e040 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
2e050 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
2e060 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
2e070 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2e080 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
2e090 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
2e0a0 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69  >.**.** <p>^sqli
2e0b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2e0c0 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20 73 71   differs from sq
2e0d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e0e0 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69 6e  () only in havin
2e0f0 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 20 70  g.** the extra p
2e100 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74  repFlags paramet
2e110 65 72 2c 20 77 68 69 63 68 20 69 73 20 61 20 62  er, which is a b
2e120 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69 73 74  it array consist
2e130 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a  ing of zero or.*
2e140 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
2e150 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2e160 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 45 5f  RSISTENT|SQLITE_
2e170 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67 73  PREPARE_*] flags
2e180 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2e190 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
2e1a0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
2e1b0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
2e1c0 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70   as.** sqlite3_p
2e1d0 72 65 70 61 72 65 5f 76 33 28 29 20 77 69 74 68  repare_v3() with
2e1e0 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c 61 67   a zero prepFlag
2e1f0 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a  s parameter..*/.
2e200 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2e210 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
2e220 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2e230 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2e240 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2e250 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2e260 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2e270 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2e280 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2e290 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2e2a0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2e2b0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2e2c0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2e2d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2e2e0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2e2f0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2e300 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2e310 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2e320 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2e330 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2e340 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
2e350 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2e360 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2e370 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2e380 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2e390 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2e3a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2e3b0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2e3c0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2e3d0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2e3e0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2e3f0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2e400 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2e410 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2e420 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2e430 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2e440 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2e450 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2e460 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2e470 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2e480 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2e490 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
2e4a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e4b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2e4c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2e4d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2e4e0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2e4f0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2e500 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2e510 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2e520 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2e530 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2e540 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2e550 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2e560 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2e570 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70    unsigned int p
2e580 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72  repFlags, /* Zer
2e590 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45  o or more SQLITE
2e5a0 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20  _PREPARE_ flags 
2e5b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2e5c0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2e5d0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2e5e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2e5f0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2e600 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2e610 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2e620 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2e630 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e640 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2e650 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
2e660 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2e670 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2e680 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2e690 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2e6a0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2e6b0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2e6c0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2e6d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e6e0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2e6f0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2e700 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2e710 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2e720 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2e730 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2e740 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2e750 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2e760 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2e770 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2e780 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
2e790 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2e7a0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
2e7b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2e7c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2e7d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2e7e0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2e7f0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2e800 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2e810 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2e820 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2e830 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2e840 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2e850 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2e860 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2e870 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2e880 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2e890 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2e8a0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2e8b0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2e8c0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2e8d0 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
2e8e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
2e8f0 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73  repare16_v3(.  s
2e900 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2e910 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2e920 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2e930 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2e940 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2e950 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2e960 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2e970 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2e980 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2e990 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2e9a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e  n bytes. */.  un
2e9b0 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46  signed int prepF
2e9c0 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72  lags, /* Zero or
2e9d0 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45   more SQLITE_PRE
2e9e0 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20  PARE_ flags */. 
2e9f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2ea00 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2ea10 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2ea20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2ea30 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2ea40 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2ea50 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2ea60 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
2ea70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ea80 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
2ea90 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48  ment SQL.** METH
2eaa0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2eab0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2eac0 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  te3_sql(P) inter
2ead0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2eae0 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79  ointer to a copy
2eaf0 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a   of the UTF-8.**
2eb00 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
2eb10 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72  o create [prepar
2eb20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20  ed statement] P 
2eb30 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61  if P was.** crea
2eb40 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2eb50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2eb60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2eb70 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
2eb80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2eb90 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2eba0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
2ebb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ebc0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2ebd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ebe0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2ebf0 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2ec00 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2ec10 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2ec20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ec30 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2ec40 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2ec50 61 6e 64 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  anded..** ^The s
2ec60 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65  qlite3_normalize
2ec70 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2ec80 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2ec90 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2eca0 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2ecb0 6e 69 6e 67 20 74 68 65 20 6e 6f 72 6d 61 6c 69  ning the normali
2ecc0 7a 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20  zed SQL text of 
2ecd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ece0 6e 74 20 50 2e 20 20 54 68 65 0a 2a 2a 20 73 65  nt P.  The.** se
2ecf0 6d 61 6e 74 69 63 73 20 75 73 65 64 20 74 6f 20  mantics used to 
2ed00 6e 6f 72 6d 61 6c 69 7a 65 20 61 20 53 51 4c 20  normalize a SQL 
2ed10 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 75 6e  statement are un
2ed20 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 73 75  specified and su
2ed30 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61 6e  bject.** to chan
2ed40 67 65 2e 20 20 41 74 20 61 20 6d 69 6e 69 6d 75  ge.  At a minimu
2ed50 6d 2c 20 6c 69 74 65 72 61 6c 20 76 61 6c 75 65  m, literal value
2ed60 73 20 77 69 6c 6c 20 62 65 20 72 65 70 6c 61 63  s will be replac
2ed70 65 64 20 77 69 74 68 20 73 75 69 74 61 62 6c 65  ed with suitable
2ed80 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2ed90 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2eda0 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70  ample, if a prep
2edb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2edc0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  s created using 
2edd0 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20  the SQL.** text 
2ede0 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2edf0 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65  z" and if parame
2ee00 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e  ter $abc is boun
2ee10 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34  d to integer 234
2ee20 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74  5.** and paramet
2ee30 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75  er :xyz is unbou
2ee40 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  nd, then sqlite3
2ee50 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75  _sql() will retu
2ee60 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  rn.** the origin
2ee70 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45  al string, "SELE
2ee80 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75  CT $abc,:xyz" bu
2ee90 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  t sqlite3_expand
2eea0 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c  ed_sql().** will
2eeb0 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20   return "SELECT 
2eec0 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a  2345,NULL".)^.**
2eed0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2eee0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20  _expanded_sql() 
2eef0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ef00 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  s NULL if insuff
2ef10 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a  icient memory.**
2ef20 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f   is available to
2ef30 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
2ef40 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73 75  , or if the resu
2ef50 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20  lt would exceed 
2ef60 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d  the.** the maxim
2ef70 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68  um string length
2ef80 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
2ef90 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  he [SQLITE_LIMIT
2efa0 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20  _LENGTH]..**.** 
2efb0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  ^The [SQLITE_TRA
2efc0 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
2efd0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2efe0 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69  on limits the si
2eff0 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70  ze of.** bound p
2f000 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69  arameter expansi
2f010 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ons.  ^The [SQLI
2f020 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63  TE_OMIT_TRACE] c
2f030 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
2f040 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c  ption causes sql
2f050 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2f060 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65  l() to always re
2f070 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  turn NULL..**.**
2f080 20 5e 54 68 65 20 73 74 72 69 6e 67 73 20 72 65   ^The strings re
2f090 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2f0a0 33 5f 73 71 6c 28 50 29 20 61 6e 64 20 73 71 6c  3_sql(P) and sql
2f0b0 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f  ite3_normalized_
2f0c0 73 71 6c 28 50 29 0a 2a 2a 20 61 72 65 20 6d 61  sql(P).** are ma
2f0d0 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20  naged by SQLite 
2f0e0 61 6e 64 20 61 72 65 20 61 75 74 6f 6d 61 74 69  and are automati
2f0f0 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e  cally freed when
2f100 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
2f110 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2f120 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65  nalized..** ^The
2f130 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2f140 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61   by sqlite3_expa
2f150 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20  nded_sql(P), on 
2f160 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a  the other hand,.
2f170 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66  ** is obtained f
2f180 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2f190 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20  loc()] and must 
2f1a0 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61  be free by the a
2f1b0 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79  pplication.** by
2f1c0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
2f1d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2f1e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2f1f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2f200 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
2f210 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 53 51 4c  tmt *pStmt);.SQL
2f220 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
2f230 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2f240 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2f250 2a 70 53 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f  *pStmt);.SQLITE_
2f260 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2f270 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a  sqlite3_normaliz
2f280 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2f290 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2f2a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2f2b0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
2f2c0 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
2f2d0 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
2f2e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f2f0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2f300 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2f310 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
2f320 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2f330 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2f340 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
2f350 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2f360 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
2f370 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
2f380 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
2f390 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2f3a0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
2f3b0 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
2f3c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f3d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
2f3e0 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
2f3f0 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
2f400 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2f410 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
2f420 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
2f430 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2f440 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
2f450 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
2f460 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
2f470 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
2f480 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
2f490 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
2f4a0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
2f4b0 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
2f4c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2f4d0 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
2f4e0 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
2f4f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2f500 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
2f510 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
2f520 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
2f530 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
2f540 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
2f550 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
2f560 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
2f570 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2f580 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
2f590 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
2f5a0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2f5b0 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
2f5c0 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
2f5d0 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
2f5e0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
2f5f0 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
2f600 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
2f610 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
2f620 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
2f630 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
2f640 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2f650 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2f660 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
2f670 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
2f680 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
2f690 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
2f6a0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2f6b0 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
2f6c0 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
2f6d0 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
2f6e0 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
2f6f0 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
2f700 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
2f710 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
2f720 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
2f730 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
2f740 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2f750 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2f760 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
2f770 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
2f780 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
2f790 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
2f7a0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
2f7b0 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
2f7c0 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
2f7d0 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
2f7e0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2f7f0 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
2f800 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  k..** ^The sqlit
2f810 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2f820 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2f830 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42  urns true for [B
2f840 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b  EGIN] since.** [
2f850 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65  BEGIN] merely se
2f860 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67  ts internal flag
2f870 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49  s, but the [BEGI
2f880 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54  N|BEGIN IMMEDIAT
2f890 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e  E] and.** [BEGIN
2f8a0 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45  |BEGIN EXCLUSIVE
2f8b0 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f  ] commands do to
2f8c0 75 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  uch the database
2f8d0 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74   and so.** sqlit
2f8e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2f8f0 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  () returns false
2f900 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61   for those comma
2f910 6e 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  nds..*/.SQLITE_A
2f920 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
2f930 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
2f940 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2f950 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f960 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2f970 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2f980 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
2f990 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eset.** METHOD: 
2f9a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2f9b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f9c0 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
2f9d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2f9e0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
2f9f0 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
2fa00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2fa10 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
2fa20 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
2fa30 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2fa40 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
2fa50 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74  as neither run t
2fa60 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65  o completion (re
2fa70 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2fa80 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71  E_DONE] from [sq
2fa90 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20  lite3_step(S)]) 
2faa0 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  nor.** been rese
2fab0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2fac0 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
2fad0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2fae0 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
2faf0 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
2fb00 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
2fb10 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
2fb20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
2fb30 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
2fb40 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
2fb50 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
2fb60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2fb70 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
2fb80 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2fb90 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2fba0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
2fbb0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
2fbc0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2fbd0 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
2fbe0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
2fbf0 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
2fc00 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
2fc10 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
2fc20 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
2fc30 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
2fc40 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
2fc50 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
2fc60 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
2fc70 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
2fc80 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
2fc90 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
2fca0 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
2fcb0 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
2fcc0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
2fcd0 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
2fce0 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
2fcf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2fd00 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2fd10 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
2fd20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fd30 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
2fd40 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
2fd50 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2fd60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2fd70 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
2fd80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2fd90 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
2fda0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
2fdb0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2fdc0 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
2fdd0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
2fde0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
2fdf0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
2fe00 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
2fe10 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
2fe20 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
2fe30 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
2fe40 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
2fe50 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2fe60 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
2fe70 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
2fe80 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
2fe90 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
2fea0 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
2feb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2fec0 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
2fed0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
2fee0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
2fef0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
2ff00 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
2ff10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ff20 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
2ff30 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
2ff40 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
2ff50 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
2ff60 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2ff70 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
2ff80 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
2ff90 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
2ffa0 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
2ffb0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
2ffc0 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
2ffd0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
2ffe0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fff0 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
30000 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
30010 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
30020 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
30030 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
30040 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
30050 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
30060 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
30070 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
30080 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
30090 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
300a0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
300b0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
300c0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
300d0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
300e0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
300f0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
30100 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
30110 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
30120 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
30130 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
30140 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
30150 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
30160 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
30170 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
30180 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
30190 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
301a0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
301b0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
301c0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
301d0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
301e0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
301f0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
30200 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
30210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
30220 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
30230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
30240 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
30250 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
30260 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
30270 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
30280 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
30290 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
302a0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
302b0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
302c0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
302d0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
302e0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
302f0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
30300 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
30310 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
30320 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
30330 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
30340 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
30350 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
30360 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
30370 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
30380 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
30390 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
303a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
303b0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
303c0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
303d0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
303e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
303f0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
30400 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
30410 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
30420 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
30430 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
30440 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
30450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
30460 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
30470 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
30480 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30490 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
304a0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 61 73   only be used as
304b0 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f   arguments.** to
304c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
304d0 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69  _value()], [sqli
304e0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
304f0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
30500 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e  e3_value_dup()].
30510 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
30520 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
30530 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
30540 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
30550 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
30560 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
30570 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
30580 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
30590 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
305a0 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  alue sqlite3_val
305b0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
305c0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
305d0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
305e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
305f0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
30600 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
30610 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
30620 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
30630 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
30640 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
30650 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
30660 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
30670 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
30680 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
30690 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
306a0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
306b0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
306c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
306d0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
306e0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
306f0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
30700 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
30710 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
30720 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
30730 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
30740 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
30750 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
30760 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
30770 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
30780 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
30790 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
307a0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
307b0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
307c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
307d0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
307e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
307f0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
30800 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
30810 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
30820 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
30830 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
30840 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
30850 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
30860 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
30870 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
30880 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
30890 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
308a0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
308b0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
308c0 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
308d0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
308e0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
308f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
30900 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
30910 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
30920 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
30930 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
30940 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
30950 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
30960 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
30970 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
30980 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
30990 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
309a0 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
309b0 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
309c0 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
309d0 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
309e0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
309f0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
30a00 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
30a10 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
30a20 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
30a30 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
30a40 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
30a50 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
30a60 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
30a70 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
30a80 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
30a90 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
30aa0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
30ab0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
30ac0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
30ad0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
30ae0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
30af0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
30b00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
30b10 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
30b20 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
30b30 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
30b40 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
30b50 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
30b60 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
30b70 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
30b80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
30b90 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
30ba0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
30bb0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
30bc0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
30bd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
30be0 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
30bf0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
30c00 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
30c10 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
30c20 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
30c30 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
30c40 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
30c50 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
30c60 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
30c70 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
30c80 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
30c90 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
30ca0 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
30cb0 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
30cc0 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
30cd0 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
30ce0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
30cf0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30d00 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
30d10 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
30d20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
30d30 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
30d40 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
30d50 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
30d60 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
30d70 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
30d80 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
30d90 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
30da0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
30db0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
30dc0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
30dd0 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
30de0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
30df0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
30e00 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
30e10 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
30e20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
30e30 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
30e40 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
30e50 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
30e60 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
30e70 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
30e80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
30e90 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
30ea0 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
30eb0 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
30ec0 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
30ed0 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
30ee0 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
30ef0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
30f00 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
30f10 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
30f20 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
30f30 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
30f40 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
30f50 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
30f60 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
30f70 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
30f80 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
30f90 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
30fa0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
30fb0 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
30fc0 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
30fd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
30fe0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
30ff0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
31000 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
31010 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
31020 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
31030 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
31040 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31050 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
31060 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
31070 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
31080 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
31090 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
310a0 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
310b0 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
310c0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
310d0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
310e0 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
310f0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
31100 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
31110 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
31120 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
31130 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
31140 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
31150 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
31160 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
31170 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
31180 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
31190 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
311a0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
311b0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
311c0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
311d0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
311e0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
311f0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
31200 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
31210 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
31220 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
31230 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
31240 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
31250 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
31260 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
31270 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
31280 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
31290 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
312a0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
312b0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
312c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
312d0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
312e0 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
312f0 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
31300 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
31310 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
31320 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
31330 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
31340 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
31350 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
31360 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
31370 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
31380 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
31390 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
313a0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
313b0 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
313c0 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
313d0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
313e0 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
313f0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
31400 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
31410 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
31420 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
31430 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
31440 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
31450 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
31460 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
31470 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
31480 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
31490 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
314a0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
314b0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
314c0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
314d0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
314e0 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
314f0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
31500 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
31510 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
31520 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
31530 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
31540 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
31550 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
31560 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
31570 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
31580 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
31590 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
315a0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
315b0 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
315c0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
315d0 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
315e0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
315f0 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
31600 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
31610 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
31620 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
31630 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
31640 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
31650 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
31660 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
31670 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
31680 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
31690 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
316a0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
316b0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
316c0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
316d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
316e0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
316f0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
31700 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
31710 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
31720 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
31730 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
31740 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
31750 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
31760 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
31770 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
31780 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
31790 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
317a0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
317b0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
317c0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
317d0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
317e0 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
317f0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
31800 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
31810 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
31820 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
31830 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
31840 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
31850 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
31860 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
31870 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
31880 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OB..**.** ^The s
31890 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
318a0 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72  ter(S,I,P,T,D) r
318b0 6f 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68  outine causes th
318c0 65 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e I-th parameter
318d0 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   in.** [prepared
318e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f   statement] S to
318f0 20 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c   have an SQL val
31900 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20  ue of NULL, but 
31910 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73  to also be.** as
31920 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
31930 65 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74  e pointer P of t
31940 79 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69  ype T.  ^D is ei
31950 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
31960 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e  ter or.** a poin
31970 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63  ter to a destruc
31980 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72  tor function for
31990 20 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c   P. ^SQLite will
319a0 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64   invoke the.** d
319b0 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
319c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
319d0 6e 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20  nt of P when it 
319e0 69 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  is finished usin
319f0 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70  g.** P.  The T p
31a00 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
31a10 62 65 20 61 20 73 74 61 74 69 63 20 73 74 72 69  be a static stri
31a20 6e 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61  ng, preferably a
31a30 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72   string.** liter
31a40 61 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f  al. The sqlite3_
31a50 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72  bind_pointer() r
31a60 6f 75 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f  outine is part o
31a70 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65  f the.** [pointe
31a80 72 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66  r passing interf
31a90 61 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53  ace] added for S
31aa0 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a  QLite 3.20.0..**
31ab0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
31ac0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
31ad0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
31ae0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
31af0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
31b00 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
31b10 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
31b20 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
31b30 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
31b40 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
31b50 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
31b60 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
31b70 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
31b80 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
31b90 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
31ba0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
31bb0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
31bc0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
31bd0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
31be0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
31bf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
31c00 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
31c10 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
31c20 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
31c30 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
31c40 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
31c50 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
31c60 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
31c70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31c80 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
31c90 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
31ca0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
31cb0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
31cc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
31cd0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
31ce0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
31cf0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
31d00 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
31d10 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
31d20 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
31d30 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
31d40 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
31d50 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
31d60 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
31d70 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
31d80 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
31d90 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
31da0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
31db0 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
31dc0 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
31dd0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
31de0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
31df0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
31e00 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
31e10 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
31e20 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
31e30 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
31e40 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
31e50 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
31e60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
31e70 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
31e80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
31e90 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
31ea0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
31eb0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
31ec0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
31ed0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
31ee0 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
31ef0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
31f00 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
31f10 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
31f20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
31f30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
31f40 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
31f50 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
31f60 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
31f70 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
31f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
31f90 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
31fa0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31fb0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
31fc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31fd0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
31fe0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31ff0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
32000 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32010 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
32020 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32030 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
32040 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
32050 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
32060 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
32070 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
32080 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32090 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
320a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
320b0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
320c0 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
320d0 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
320e0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
320f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32100 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
32110 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
32120 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
32130 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
32140 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
32150 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
32160 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
32170 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
32180 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
32190 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
321a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
321b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
321c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
321d0 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f  coding);.SQLITE_
321e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
321f0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
32200 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
32210 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
32220 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
32230 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
32240 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65  d_pointer(sqlite
32250 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f  3_stmt*, int, vo
32260 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  id*, const char*
32270 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
32280 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
32290 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
322a0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
322b0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
322c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
322d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
322e0 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
322f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
32300 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
32310 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32320 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
32330 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
32340 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
32350 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
32360 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
32370 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
32380 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
32390 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
323a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
323b0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
323c0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
323d0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
323e0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
323f0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
32400 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
32410 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
32420 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
32430 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
32440 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
32450 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
32460 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
32470 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
32480 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
32490 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
324a0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
324b0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
324c0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
324d0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
324e0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
324f0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
32500 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
32510 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
32520 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
32530 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
32540 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
32550 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
32560 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
32570 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
32580 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
32590 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
325a0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
325b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
325c0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
325d0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
325e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
325f0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
32600 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
32610 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
32620 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
32630 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
32640 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
32650 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
32660 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  er.** METHOD: sq
32670 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
32680 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
32690 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
326a0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
326b0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
326c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
326d0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
326e0 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
326f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
32700 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
32710 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
32720 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
32730 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
32740 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
32750 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
32760 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
32770 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
32780 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
32790 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
327a0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
327b0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
327c0 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
327d0 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
327e0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
327f0 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
32800 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
32810 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
32820 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
32830 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
32840 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
32850 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
32860 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
32870 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
32880 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
32890 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
328a0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
328b0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
328c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
328d0 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
328e0 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
328f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
32900 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
32910 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
32920 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
32930 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
32940 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
32950 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
32960 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
32970 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
32980 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
32990 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
329a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
329b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
329c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
329d0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
329e0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
329f0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
32a00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
32a10 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
32a20 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
32a30 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
32a40 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
32a50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
32a60 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
32a70 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
32a80 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
32a90 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
32aa0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
32ab0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
32ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
32ad0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
32ae0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
32af0 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ame.** METHOD: s
32b00 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32b10 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
32b20 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
32b30 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
32b40 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
32b50 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
32b60 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
32b70 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
32b80 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
32b90 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
32ba0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
32bb0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
32bc0 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
32bd0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
32be0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
32bf0 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
32c00 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
32c10 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
32c20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
32c30 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
32c40 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
32c50 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
32c60 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
32c70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
32c80 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
32c90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
32ca0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
32cb0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
32cc0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
32cd0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
32ce0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
32cf0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
32d00 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
32d10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
32d20 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  e()]..*/.SQLITE_
32d30 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32d40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
32d50 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
32d60 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
32d70 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
32d80 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
32d90 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
32da0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
32db0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
32dc0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32dd0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
32de0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
32df0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
32e00 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
32e10 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
32e20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
32e30 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
32e40 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
32e50 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
32e60 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
32e70 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
32e80 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
32e90 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
32ea0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65   int sqlite3_cle
32eb0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
32ec0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
32ed0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
32ee0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
32ef0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
32f00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32f10 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
32f20 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
32f30 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
32f40 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
32f50 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
32f60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32f70 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72  ent]. ^If this r
32f80 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
32f90 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
32fa0 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
32fb0 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e  tatement] return
32fc0 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65  s no data (for e
32fd0 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
32fe0 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72  E])..** ^However
32ff0 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 74  , just because t
33000 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
33010 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
33020 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a  umber does not.*
33030 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20  * mean that one 
33040 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20  or more rows of 
33050 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74  data will be ret
33060 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43  urned.  ^A SELEC
33070 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  T statement.** w
33080 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20  ill always have 
33090 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74  a positive sqlit
330a0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
330b0 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20  ) but depending 
330c0 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20  on the.** WHERE 
330d0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
330e0 74 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65  ts and the table
330f0 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67   content, it mig
33100 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77  ht return no row
33110 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
33120 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
33130 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
33140 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
33150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
33160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
33170 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
33180 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
33190 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
331a0 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
331b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
331c0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
331d0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
331e0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
331f0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
33200 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
33210 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
33220 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
33230 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
33240 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
33250 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
33260 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
33270 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
33280 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
33290 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
332a0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
332b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
332c0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
332d0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
332e0 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
332f0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
33300 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
33310 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
33320 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
33330 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
33340 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
33350 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
33360 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
33370 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
33380 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
33390 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
333a0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
333b0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
333c0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
333d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
333e0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
333f0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
33400 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
33410 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
33420 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
33430 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
33440 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
33450 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
33460 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
33470 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
33480 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
33490 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
334a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
334b0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
334c0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
334d0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
334e0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
334f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
33500 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
33510 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
33520 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
33530 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
33540 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
33550 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
33560 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
33570 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
33580 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
33590 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
335a0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
335b0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
335c0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
335d0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
335e0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
335f0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
33600 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
33610 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
33620 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
33630 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
33640 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
33650 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
33660 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
33670 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
33680 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
33690 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
336a0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
336b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
336c0 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
336d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
336e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
336f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33700 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
33710 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
33720 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
33730 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
33740 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
33750 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
33760 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
33770 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
33780 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
33790 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
337a0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
337b0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
337c0 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
337d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
337e0 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
337f0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
33800 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
33810 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
33820 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
33830 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
33840 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
33850 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
33860 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
33870 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
33880 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
33890 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
338a0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
338b0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
338c0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
338d0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
338e0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
338f0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
33900 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
33910 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
33920 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
33930 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
33940 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
33950 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
33960 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
33970 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
33980 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
33990 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
339a0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
339b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
339c0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
339d0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
339e0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
339f0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
33a00 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
33a10 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
33a20 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
33a30 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
33a40 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
33a50 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
33a60 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
33a70 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
33a80 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
33a90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
33aa0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
33ab0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
33ac0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
33ad0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
33ae0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
33af0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
33b00 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
33b10 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
33b20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
33b30 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
33b40 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
33b50 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
33b60 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
33b70 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
33b80 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
33b90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
33ba0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
33bb0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
33bc0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
33bd0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
33be0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
33bf0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
33c00 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
33c10 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
33c20 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
33c30 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
33c40 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
33c50 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
33c60 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
33c70 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
33c80 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
33c90 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
33ca0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
33cb0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
33cc0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
33cd0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
33ce0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
33cf0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
33d00 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
33d10 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
33d20 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
33d30 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
33d40 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
33d50 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
33d60 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
33d70 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
33d80 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
33d90 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
33da0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
33db0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
33dc0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
33dd0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
33de0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
33df0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
33e00 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
33e10 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
33e20 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
33e30 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
33e40 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
33e50 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
33e60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
33e70 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
33e80 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
33e90 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
33ea0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
33eb0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
33ec0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
33ed0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
33ee0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33ef0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
33f00 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
33f10 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
33f20 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
33f30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33f40 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
33f50 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
33f60 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
33f70 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
33f80 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
33f90 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
33fa0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
33fb0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
33fc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
33fd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
33fe0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33ff0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
34000 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
34010 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
34020 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
34030 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
34040 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
34050 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
34060 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
34070 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
34080 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
34090 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
340a0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
340b0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
340c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
340d0 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
340e0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
340f0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
34100 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
34110 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
34120 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
34130 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
34140 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
34150 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
34160 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
34170 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
34180 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  mt.**.** ^(The f
34190 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
341a0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
341b0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
341c0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
341d0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
341e0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
341f0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
34200 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
34210 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
34220 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
34230 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
34240 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
34250 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
34260 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
34270 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
34280 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
34290 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
342a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
342b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
342c0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
342d0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
342e0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
342f0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
34300 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
34310 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
34320 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
34330 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
34340 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
34350 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
34360 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
34370 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
34380 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
34390 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
343a0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
343b0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
343c0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
343d0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
343e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
343f0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
34400 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
34410 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
34420 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
34430 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
34440 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
34450 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
34460 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
34470 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
34480 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
34490 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
344a0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
344b0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
344c0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
344d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
344e0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
344f0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
34500 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
34510 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
34520 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
34530 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
34540 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
34550 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
34560 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
34570 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
34580 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
34590 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
345a0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
345b0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
345c0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
345d0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
345e0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
345f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
34600 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
34610 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
34620 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
34630 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
34640 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
34650 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
34660 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
34670 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
34680 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
34690 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
346a0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41  te3_stmt.**.** A
346b0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
346c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
346d0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
346e0 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73  ing any of.** [s
346f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
34700 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
34710 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
34720 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
34730 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  _v2()],.** or [s
34740 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
34750 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v3()] or one of
34760 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
34770 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
34780 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
34790 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
347a0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
347b0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
347c0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
347d0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
347e0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
347f0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
34800 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
34810 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
34820 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
34830 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
34840 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
34850 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
34860 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
34870 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65   newer "vX" inte
34880 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  rfaces.** [sqlit
34890 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
348a0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
348b0 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
348c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
348d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
348e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
348f0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
34900 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
34910 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
34920 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
34930 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
34940 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
34950 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74  .** new "vX" int
34960 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
34970 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
34980 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
34990 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
349a0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
349b0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
349c0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
349d0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
349e0 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
349f0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
34a00 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
34a10 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
34a20 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
34a30 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
34a40 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
34a50 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
34a60 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
34a70 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
34a80 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
34a90 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
34aa0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
34ab0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
34ac0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
34ad0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
34ae0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
34af0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
34b00 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
34b10 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
34b20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
34b30 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
34b40 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
34b50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
34b60 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
34b70 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
34b80 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
34b90 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
34ba0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
34bb0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
34bc0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
34bd0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
34be0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
34bf0 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
34c00 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
34c10 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
34c20 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
34c30 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
34c40 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
34c50 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
34c60 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
34c70 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
34c80 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
34c90 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
34ca0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
34cb0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
34cc0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
34cd0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
34ce0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
34cf0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
34d00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
34d10 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
34d20 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
34d30 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
34d40 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
34d50 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
34d60 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
34d70 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
34d80 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
34d90 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
34da0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
34db0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
34dc0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
34dd0 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
34de0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
34df0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
34e00 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
34e10 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
34e20 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
34e30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
34e40 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
34e50 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
34e60 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
34e70 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
34e80 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
34e90 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
34ea0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
34eb0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
34ec0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
34ed0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
34ee0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
34ef0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
34f00 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
34f10 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
34f20 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
34f30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
34f40 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
34f50 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
34f60 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
34f70 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
34f80 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
34f90 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
34fa0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
34fb0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
34fc0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
34fd0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
34fe0 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
34ff0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
35000 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
35010 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
35020 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
35030 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
35040 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
35050 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
35060 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
35070 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
35080 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
35090 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
350a0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
350b0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
350c0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
350d0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
350e0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
350f0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
35100 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
35110 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
35120 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
35130 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
35140 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
35150 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
35160 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
35170 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
35180 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
35190 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
351a0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
351b0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
351c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
351d0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
351e0 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
351f0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
35200 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
35210 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
35220 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
35230 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
35240 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
35250 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
35260 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
35270 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
35280 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
35290 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
352a0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
352b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
352c0 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
352d0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
352e0 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
352f0 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
35300 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
35310 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35320 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
35330 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
35340 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
35350 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
35360 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
35370 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
35380 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72    But after [ver
35390 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28  sion 3.6.23.1] (
353a0 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31  [dateof:3.6.23.1
353b0 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ],.** sqlite3_st
353c0 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
353d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
353e0 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
353f0 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
35400 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
35410 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
35420 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
35430 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
35440 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
35450 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
35460 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
35470 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
35480 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
35490 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
354a0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
354b0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
354c0 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
354d0 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
354e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
354f0 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
35500 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
35510 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
35520 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
35530 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
35540 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
35550 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
35560 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
35570 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
35580 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
35590 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
355a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
355b0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
355c0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
355d0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
355e0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
355f0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
35600 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
35610 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
35620 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
35630 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
35640 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
35650 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
35660 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
35670 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
35680 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
35690 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
356a0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
356b0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
356c0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
356d0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
356e0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
356f0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
35700 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
35710 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  nts.** using [sq
35720 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
35730 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
35740 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
35750 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
35760 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
35770 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35780 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64  16_v3()] instead
35790 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
357a0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
357b0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
357c0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
357d0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
357e0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
357f0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
35800 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
35810 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
35820 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
35830 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
35840 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20  "vX" interfaces 
35850 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
35860 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
35870 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
35880 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
35890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
358a0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
358b0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
358c0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
358d0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
358e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
358f0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
35900 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
35910 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
35920 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
35930 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
35940 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
35950 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
35960 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
35970 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
35980 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
35990 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
359a0 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
359b0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
359c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
359d0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
359e0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
359f0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
35a00 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
35a10 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
35a20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
35a30 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
35a40 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
35a50 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
35a60 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
35a70 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
35a80 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
35a90 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
35aa0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
35ab0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
35ac0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
35ad0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
35ae0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
35af0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
35b00 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
35b10 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
35b20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
35b30 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
35b40 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
35b50 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
35b60 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
35b70 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
35b80 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
35b90 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
35ba0 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
35bb0 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
35bc0 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
35bd0 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
35be0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
35bf0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
35c00 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
35c10 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  mn_count()].*/.S
35c20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
35c30 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
35c40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
35c50 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
35c60 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
35c70 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
35c80 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
35c90 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
35ca0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
35cb0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
35cc0 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
35cd0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
35ce0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
35cf0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
35d00 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
35d10 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
35d20 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
35d30 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
35d40 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
35d50 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
35d60 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
35d70 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
35d80 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
35d90 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
35da0 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
35db0 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
35dc0 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
35dd0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
35de0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
35df0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
35e00 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
35e10 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
35e20 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
35e30 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
35e40 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
35e50 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
35e60 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
35e70 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
35e80 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
35e90 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
35ea0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
35eb0 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
35ec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
35ed0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
35ee0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
35ef0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
35f00 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
35f10 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
35f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
35f30 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
35f40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
35f50 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
35f60 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
35f70 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
35f80 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
35f90 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
35fa0 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
35fb0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
35fc0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53  _stmt.**.** <b>S
35fd0 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c  ummary:</b>.** <
35fe0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c  blockquote><tabl
35ff0 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70  e border=0 cellp
36000 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61  adding=0 cellspa
36010 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c  cing=0>.** <tr><
36020 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
36030 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64  lumn_blob</b><td
36040 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20  >&rarr;<td>BLOB 
36050 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
36060 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
36070 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74  umn_double</b><t
36080 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c  d>&rarr;<td>REAL
36090 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
360a0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
360b0 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e  lumn_int</b><td>
360c0 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74  &rarr;<td>32-bit
360d0 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a   INTEGER result.
360e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
360f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
36100 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  64</b><td>&rarr;
36110 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47  <td>64-bit INTEG
36120 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
36130 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
36140 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c  column_text</b><
36150 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
36160 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a  -8 TEXT result.*
36170 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
36180 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36190 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  16</b><td>&rarr;
361a0 3c 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20  <td>UTF-16 TEXT 
361b0 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
361c0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
361d0 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64  umn_value</b><td
361e0 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72  >&rarr;<td>The r
361f0 65 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20  esult as an .** 
36200 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75  [sqlite3_value|u
36210 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
36220 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36230 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62  ..** <tr><td>&nb
36240 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  sp;<td>&nbsp;<td
36250 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c  >&nbsp;.** <tr><
36260 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
36270 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74  lumn_bytes</b><t
36280 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65  d>&rarr;<td>Size
36290 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72   of a BLOB.** or
362a0 20 61 20 55 54 46 2d 38 20 54 45 58 54 20 72 65   a UTF-8 TEXT re
362b0 73 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a  sult in bytes.**
362c0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
362d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
362e0 31 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f  16&nbsp;&nbsp;</
362f0 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b  b>.** <td>&rarr;
36300 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e  &nbsp;&nbsp;<td>
36310 53 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a  Size of UTF-16.*
36320 2a 20 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a  * TEXT in bytes.
36330 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
36340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
36350 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
36360 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61  td>Default.** da
36370 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65  tatype of the re
36380 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  sult.** </table>
36390 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
363a0 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c  .** <b>Details:<
363b0 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  /b>.**.** ^These
363c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
363d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
363e0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
363f0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
36400 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
36410 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
36420 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
36430 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
36440 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
36450 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
36460 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
36470 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
36480 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
36490 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
364a0 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
364b0 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
364c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
364d0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
364e0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
364f0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
36500 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
36510 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
36520 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
36530 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
36540 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
36550 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
36560 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
36570 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
36580 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
36590 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
365a0 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
365b0 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
365c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
365d0 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
365e0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
365f0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
36600 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
36610 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
36620 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
36630 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
36640 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
36650 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
36660 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
36670 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
36680 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
36690 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
366a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
366b0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
366c0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
366d0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
366e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
366f0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
36700 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
36710 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
36720 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
36730 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
36740 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
36750 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
36760 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
36770 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36780 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
36790 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
367a0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
367b0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
367c0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
367d0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
367e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
367f0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
36800 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
36810 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
36820 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
36830 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
36840 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
36850 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
36860 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
36870 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
36880 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
36890 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
368a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
368b0 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 73  t six interfaces
368c0 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65   (_blob, _double
368d0 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20  , _int, _int64, 
368e0 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74  _text, and _text
368f0 31 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75  16).** each retu
36900 72 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  rn the value of 
36910 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
36920 69 6e 20 61 20 73 70 65 63 69 66 69 63 20 64 61  in a specific da
36930 74 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a  ta format.  If.*
36940 2a 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  * the result col
36950 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69  umn is not initi
36960 61 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75  ally in the requ
36970 65 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f  ested format (fo
36980 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66  r example,.** if
36990 20 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72   the query retur
369a0 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75  ns an integer bu
369b0 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  t the sqlite3_co
369c0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65  lumn_text() inte
369d0 72 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64  rface.** is used
369e0 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20   to extract the 
369f0 76 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61  value) then an a
36a00 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
36a10 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
36a20 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ormed..**.** ^Th
36a30 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
36a40 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
36a50 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
36a60 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
36a70 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
36a80 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
36a90 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
36aa0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
36ab0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
36ac0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
36ad0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
36ae0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
36af0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
36b00 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
36b10 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
36b20 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65  NULL]..** The re
36b30 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71  turn value of sq
36b40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
36b50 65 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20  e() can be used 
36b60 74 6f 20 64 65 63 69 64 65 20 77 68 69 63 68 0a  to decide which.
36b70 2a 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  ** of the first 
36b80 73 69 78 20 69 6e 74 65 72 66 61 63 65 20 73 68  six interface sh
36b90 6f 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20  ould be used to 
36ba0 65 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75  extract the colu
36bb0 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65  mn value..** The
36bc0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
36bd0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
36be0 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
36bf0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
36c00 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74  o.** automatic t
36c10 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
36c20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f  have occurred fo
36c30 72 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71  r the value in q
36c40 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66  uestion.  .** Af
36c50 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
36c60 72 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c  rsion, the resul
36c70 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c  t of calling sql
36c80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
36c90 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ().** is undefin
36ca0 65 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c  ed, though harml
36cb0 65 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ess.  Future.** 
36cc0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
36cd0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
36ce0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
36cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
36d00 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
36d10 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
36d20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
36d30 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
36d40 42 20 6f 72 20 61 20 54 45 58 54 20 73 74 72 69  B or a TEXT stri
36d50 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ng, then the sql
36d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36d70 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  s().** or sqlite
36d80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
36d90 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 63 61  () interfaces ca
36da0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74  n be used to det
36db0 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a  ermine the size.
36dc0 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20  ** of that BLOB 
36dd0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  or string..**.**
36de0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
36df0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
36e00 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
36e10 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
36e20 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
36e30 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
36e40 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
36e50 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
36e60 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
36e70 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
36e80 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
36e90 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
36ea0 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
36eb0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
36ec0 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
36ed0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
36ee0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
36ef0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
36f00 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
36f10 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
36f20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36f30 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
36f40 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
36f50 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
36f60 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
36f70 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
36f80 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
36f90 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
36fa0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
36fb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
36fc0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
36fd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36fe0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
36ff0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
37000 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
37010 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
37020 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
37030 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
37040 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
37050 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
37060 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
37070 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
37080 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
37090 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
370a0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
370b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
370c0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
370d0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
370e0 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
370f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
37100 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
37110 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
37120 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
37130 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
37140 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
37150 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
37160 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
37170 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
37180 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
37190 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
371a0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
371b0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
371c0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
371d0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
371e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
371f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
37200 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
37210 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
37220 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
37230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37240 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
37250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37260 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
37270 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
37280 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
37290 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
372a0 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
372b0 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
372c0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
372d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
372e0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
372f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37300 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
37310 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
37320 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
37330 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
37340 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
37350 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
37360 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
37370 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
37380 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
37390 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
373a0 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
373b0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
373c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
373d0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
373e0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
373f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
37400 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
37410 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
37420 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
37430 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f  ** <b>Warning:</
37440 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  b> ^The object r
37450 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
37460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
37470 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
37480 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37490 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
374a0 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65    In a multithre
374b0 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  aded environment
374c0 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63  ,.** an unprotec
374d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
374e0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c  e object may onl
374f0 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79  y be used safely
37500 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
37510 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
37520 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
37530 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
37540 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
37550 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
37560 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
37570 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
37580 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
37590 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
375a0 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
375b0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
375c0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
375d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
375e0 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
375f0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
37600 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
37610 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
37620 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e  he behavior is n
37630 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a  ot threadsafe..*
37640 2a 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c  * Hence, the sql
37650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
37660 65 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  e() interface.**
37670 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c   is normally onl
37680 79 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20  y useful within 
37690 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
376a0 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69  on of .** [appli
376b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
376c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
376d0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
376e0 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a  ], not within.**
376f0 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69   top-level appli
37700 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a  cation code..**.
37710 2a 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f 75  ** The these rou
37720 74 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70  tines may attemp
37730 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
37740 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
37750 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72   result..** ^For
37760 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
37770 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
37780 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
37790 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
377a0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
377b0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
377c0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
377d0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
377e0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
377f0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
37800 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
37810 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
37820 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
37830 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
37840 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
37850 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
37860 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
37870 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
37880 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
37890 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
378a0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
378b0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
378c0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
378d0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
378e0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
378f0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
37900 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
37910 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
37920 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
37930 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
37940 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
37950 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
37960 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
37970 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
37980 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
37990 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
379a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
379b0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
379c0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
379d0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
379e0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
379f0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
37a00 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
37a10 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
37a20 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
37a30 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
37a40 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
37a50 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
37a60 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
37a70 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
37a80 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
37a90 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
37aa0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
37ab0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
37ac0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
37ad0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
37ae0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
37af0 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
37b00 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
37b10 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
37b20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
37b30 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
37b40 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
37b50 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
37b60 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
37b70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
37b80 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
37b90 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
37ba0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
37bb0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
37bc0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
37bd0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
37be0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
37bf0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
37c00 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
37c10 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
37c20 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
37c30 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
37c40 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
37c50 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
37c60 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
37c70 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
37c80 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
37c90 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
37ca0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
37cb0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  te>)^.**.** Note
37cc0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
37cd0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
37ce0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
37cf0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
37d00 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
37d10 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
37d20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37d30 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
37d40 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
37d50 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
37d60 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
37d70 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
37d80 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
37d90 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
37da0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
37db0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
37dc0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
37dd0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
37de0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
37df0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
37e00 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
37e10 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
37e20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
37e30 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
37e40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
37e50 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
37e60 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
37e70 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
37e80 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
37e90 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
37ea0 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
37eb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37ec0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
37ed0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
37ee0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
37ef0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
37f00 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
37f10 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
37f20 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
37f30 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
37f40 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
37f50 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
37f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37f70 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
37f80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37f90 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
37fa0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
37fb0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
37fc0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
37fd0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
37fe0 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
37ff0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
38000 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
38010 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
38020 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
38030 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
38040 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
38050 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
38060 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
38070 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
38080 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
38090 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
380a0 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
380b0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
380c0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
380d0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
380e0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
380f0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
38100 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
38110 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
38120 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
38130 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
38140 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
38150 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
38160 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69   The safest poli
38170 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
38180 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
38190 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
381a0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
381b0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
381c0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
381d0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
381e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
381f0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
38200 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
38210 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
38220 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
38230 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
38240 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
38250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
38260 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
38270 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
38280 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
38290 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
382a0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
382b0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
382c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
382d0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
382e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
382f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
38300 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
38310 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
38320 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
38330 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
38340 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
38350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
38360 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
38370 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
38380 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
38390 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
383a0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
383b0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
383c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
383d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
383e0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
383f0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
38400 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
38410 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
38420 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
38430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
38440 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
38450 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
38460 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
38470 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
38480 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
38490 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
384a0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
384b0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
384c0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
384d0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
384e0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
384f0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
38500 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
38510 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
38520 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
38530 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
38540 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
38550 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
38560 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
38570 6f 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70  o not pass the p
38580 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
38590 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
385a0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
385b0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
385c0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
385d0 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
385e0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
385f0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 69  As long as the i
38600 6e 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  nput parameters 
38610 61 72 65 20 63 6f 72 72 65 63 74 2c 20 74 68 65  are correct, the
38620 73 65 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  se routines will
38630 20 6f 6e 6c 79 0a 2a 2a 20 66 61 69 6c 20 69 66   only.** fail if
38640 20 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72   an out-of-memor
38650 79 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  y error occurs d
38660 75 72 69 6e 67 20 61 20 66 6f 72 6d 61 74 20 63  uring a format c
38670 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 4f 6e  onversion..** On
38680 6c 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ly the following
38690 20 73 75 62 73 65 74 20 6f 66 20 69 6e 74 65 72   subset of inter
386a0 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63  faces are subjec
386b0 74 20 74 6f 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  t t