/ Hex Artifact Content
Login

Artifact 56cde49c323e5469aee0736582caccf45eaf1a03aab4407af5f738731a78f9f8:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6c 73 65 0a 23 20 64  nt N);.#else.# d
1e00: 65 66 69 6e 65 20 73 71 6c 69 74 65 33 5f 63 6f  efine sqlite3_co
1e10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1e20: 28 58 29 20 30 0a 23 20 64 65 66 69 6e 65 20 73  (X) 0.# define s
1e30: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1e40: 74 69 6f 6e 5f 67 65 74 28 58 29 20 20 28 28 76  tion_get(X)  ((v
1e50: 6f 69 64 2a 29 30 29 0a 23 65 6e 64 69 66 0a 0a  oid*)0).#endif..
1e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e70: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1e80: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1e90: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1eb0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ec0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1ed0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1ee0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1ef0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1f00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1f10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1f20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1f50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1f60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1f70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1f80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1f90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1fa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1fb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1fc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1fd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1fe0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1ff0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
2000: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
2010: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2020: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
2030: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
2040: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
2050: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
2060: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
2070: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
2080: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
2090: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
20a0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
20b0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
20c0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
20d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
20e0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
20f0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
2100: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
2110: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
2120: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
2130: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
2140: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
2150: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
2160: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
2170: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
2180: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
2190: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
21a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
21b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
21c0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
21d0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
21e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
21f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
2200: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
2210: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
2220: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2230: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
2240: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
2250: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2260: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
2270: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
2280: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2290: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
22a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
22b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
22c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
22d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
22e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
22f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2300: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2310: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2320: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2330: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2340: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2350: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2360: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2370: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2380: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2390: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
23a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
23b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
23c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
23d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
23e0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
23f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2400: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
2410: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
2420: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
2430: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2440: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
2450: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
2460: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
2470: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
2480: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
2490: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
24a0: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
24b0: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
24c0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
24d0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
24e0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
24f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2500: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
2510: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
2520: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
2530: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2550: 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ation..*/.int sq
2560: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2570: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
2580: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2590: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
25a0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
25b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
25c0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
25d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
25e0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
25f0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2600: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2610: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2620: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2630: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
2640: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
2650: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
2660: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
2670: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
2680: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
2690: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
26a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
26b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
26c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
26d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
26e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
26f0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2710: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2720: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2730: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
2740: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2750: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
2760: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
2770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2790: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27a0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
27b0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
27c0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
27d0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
27e0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
27f0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2800: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2810: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2820: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2830: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
2840: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
2850: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
2860: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
2870: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
2880: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
2890: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
28a0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
28b0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
28c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
28d0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
28e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
28f0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2900: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2920: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2930: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
2940: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
2950: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
2960: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
2970: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2980: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
2990: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
29a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
29b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
29c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
29d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
29e0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
29f0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2a00: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2a10: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2a20: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2a30: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
2a40: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2a50: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
2a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2a70: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2a80: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
2a90: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2aa0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2ab0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2ac0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2ad0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2ae0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2af0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2b00: 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54  4;.# ifdef SQLIT
2b10: 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  E_UINT64_TYPE.  
2b20: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2b30: 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  _UINT64_TYPE sql
2b40: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c  ite_uint64;.# el
2b50: 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66  se  .    typedef
2b60: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2b70: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2b80: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64  te_uint64;.# end
2b90: 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  if.#elif defined
2ba0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
2bb0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
2bc0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
2bd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2be0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2bf0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2c00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2c10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2c20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2c50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2c60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2c70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2c90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2ca0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2cb0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2cc0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2cd0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ce0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2cf0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2d00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2d10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2d20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2d30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2d40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2d50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2d70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2d80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2d90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2da0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2db0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2dd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2df0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2e00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2e10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2e20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2e30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2e40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2e50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2e60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2e70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2e80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2e90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ea0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2eb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2ec0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ed0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ef0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2f00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2f10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2f20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2f30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2f40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2f50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2f60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2f90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2fa0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2fd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2fe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2ff0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
3000: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
3010: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
3020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3030: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
3040: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
3050: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
3060: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
3070: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
3080: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30a0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
30b0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
30c0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
30d0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
30e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
30f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
3100: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
3110: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
3120: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
3130: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
3140: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
3150: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
3160: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
3170: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
3180: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
3190: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31b0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
31c0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
31d0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
31e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
31f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3200: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3210: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3220: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3230: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3240: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3250: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3260: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3280: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3290: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
32a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
32c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
32f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3300: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3310: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3320: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3340: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3350: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3360: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3370: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3380: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3390: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
33a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
33b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
33c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
33d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
33e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
33f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3400: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3410: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3420: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3440: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3450: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3460: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3470: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3480: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
34a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
34c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
34d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
34e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
34f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3500: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3510: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3520: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3530: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3540: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3550: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3560: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3570: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3580: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3590: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
35a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
35b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
35c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
35e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
35f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3600: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3610: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3620: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3630: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3640: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3650: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3660: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3670: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3680: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3690: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
36a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
36b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
36c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
36d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
36e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3700: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3710: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3720: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3730: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3740: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3750: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3760: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3790: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
37a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
37c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
37d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
37e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
37f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3800: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3810: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3820: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3830: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3840: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3850: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3860: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3870: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3880: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3890: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
38a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
38b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
38c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
38e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
38f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3900: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3910: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3920: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3930: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3940: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3950: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3960: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3970: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3980: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3990: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
39a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
39b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
39c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
39d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
39e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
39f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3a00: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3a10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3a40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3a50: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3a60: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3a70: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3a80: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3a90: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3aa0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3ab0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3ac0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3ad0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3ae0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3af0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3b00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3b10: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3b20: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3b30: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3b40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b60: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3b70: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3b90: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3ba0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3bb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3bc0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3bd0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bf0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3c00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3c20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3c30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3c40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3c50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3c60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3c70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3c90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3ca0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3cb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3cc0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3cd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3cf0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3d00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3d10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3d20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3d30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3d40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3d50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3d60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3d70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3d80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3d90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3da0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3db0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3dc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3dd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3de0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3df0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3e00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3e10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3e20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3e30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3e40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3e50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3e70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3e80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3e90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ea0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3eb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3ec0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3ed0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ee0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3ef0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3f00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3f10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3f20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3f30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3f40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3f50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3f60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3f70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3f80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fa0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3fb0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3fc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3fd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3fe0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ff0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
4000: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
4010: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
4020: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
4030: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
4040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
4050: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
4060: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
4070: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
4080: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
4090: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
40a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40b0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
40c0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
40d0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
40e0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
40f0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
4100: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
4110: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
4120: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
4130: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
4140: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
4150: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
4160: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
4170: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
4180: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
4190: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
41b0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
41c0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
41d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
41e0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
41f0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4200: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4210: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4220: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4230: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4250: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4260: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4270: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4280: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4290: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
42a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
42b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
42c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
42d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
42e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
42f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4300: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4310: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4320: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4330: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4340: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4350: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4360: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4370: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4390: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
43a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
43b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
43e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
43f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4410: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4420: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4430: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4460: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4470: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4480: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4490: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
44a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
44c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
44d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
44e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
44f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4520: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4530: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4540: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4550: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4560: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4570: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4580: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4590: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
45a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
45b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
45c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
45d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
45e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
45f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4600: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4620: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4630: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4640: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4650: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4670: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4680: 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f   /* Generic erro
4690: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
46a0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
46b0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
46c0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
46d0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
46f0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4700: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4710: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4720: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4730: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4740: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4750: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4770: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4780: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4790: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
47a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47b0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
47c0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
47d0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
47e0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4800: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4810: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4820: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4830: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4840: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4850: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4860: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4880: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4890: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
48a0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
48b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48d0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
48e0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
48f0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4900: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4920: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4930: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4940: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4950: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4960: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4970: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4980: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4990: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
49a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
49b0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
49c0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
49d0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
49e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
49f0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4a00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4a10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4a20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4a30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4a50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4a60: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4a70: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4a90: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4aa0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20  /* Internal use 
4ab0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
4ac0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4ad0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4ae0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4af0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4b10: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4b20: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4b30: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4b40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4b60: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4b70: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4b80: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4ba0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4bb0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4bc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4bd0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4be0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4bf0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c10: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4c20: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4c30: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4c40: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4c60: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4c70: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4c80: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4c90: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ca0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74       24   /* Not
4cb0: 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
4cc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
4cd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
4ce0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4cf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
4d00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
4d20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
4d30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
4d40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
4d50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4d60: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
4d70: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
4d80: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
4d90: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
4db0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
4dc0: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
4dd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4df0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
4e00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4e10: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
4e20: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
4e30: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
4e40: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
4e50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4e60: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
4e70: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
4e80: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4e90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4ea0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
4eb0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4ec0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
4ee0: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e  itions}.**.** In
4ef0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4f00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4f10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4f20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30  return one of 30
4f30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73   integer.** [res
4f40: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4f50: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4f60: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4f70: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4f80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f90: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4fa0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4fb0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4fc0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4fd0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4fe0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4ff0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
5000: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
5010: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
5020: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
5030: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
5040: 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e  3.3.8 [dateof:3.
5050: 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65  3.8].** and late
5060: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
5070: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
5080: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
5090: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
50a0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
50b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
50c0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
50d0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
50e0: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
50f0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
5100: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
5110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
5120: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
5130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
5140: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
5150: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
5160: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
5170: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
5180: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
5190: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
51a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
51b0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
51c0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
51d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53  SQLITE_ERROR_MIS
51e0: 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28  SING_COLLSEQ   (
51f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28  SQLITE_ERROR | (
5200: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5210: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52  QLITE_ERROR_RETR
5220: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  Y             (S
5230: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32  QLITE_ERROR | (2
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5250: 4c 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53  LITE_ERROR_SNAPS
5260: 48 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51  HOT          (SQ
5270: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c  LITE_ERROR | (3<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
52c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
52d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
52e0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
52f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5300: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5310: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5320: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5330: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5350: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5370: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
53a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
53c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
53d0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
53e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
53f0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5410: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5420: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5430: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5450: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5470: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5490: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54b0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
55e0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
55f0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56d0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56f0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5710: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5720: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5730: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5750: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5760: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5770: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5780: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5790: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
57a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57b0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
57c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57d0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
57e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57f0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5810: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5820: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5830: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5840: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5850: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5860: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5870: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5890: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
58a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58b0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58d0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58f0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5910: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5920: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5930: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5950: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5960: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5970: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5990: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59b0: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
59d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59f0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5a10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5a30: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a50: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a70: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5a90: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5ab0: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<8)).#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ad0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5af0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5b10: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5b30: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5b40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b50: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5b60: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5b70: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5bc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5be0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5bf0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5c20: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5c30: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5c40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5c60: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5c70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5c80: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5c90: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5cb0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5cf0: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5d00: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5d10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5d20: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5d30: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5d40: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5d50: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5d70: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5d80: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5d90: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5db0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5dd0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5df0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5e20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5e40: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5e50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5e60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5e80: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5e90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5ea0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5eb0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5ec0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5ed0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5ee0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ef0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f00: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5f10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5f30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5f40: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5f50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5f60: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5f80: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5f90: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5fc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5fd0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5ff0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6000: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6010: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6030: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
6040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6050: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
6060: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6070: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6090: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
60a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
60b0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
60c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
60d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
60e0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6110: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6120: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6140: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
6150: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6160: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
6170: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6180: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61a0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
61b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
61c0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61e0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
61f0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6200: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6220: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
6240: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
6260: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
6270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
6280: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
62a0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
62b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
62c0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
62d0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
62e0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
62f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6300: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6310: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6320: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6330: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
6340: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
6350: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
6360: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
6370: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
6380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6390: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
63a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6410: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6420: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
6460: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6470: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
64b0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
64c0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6500: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6520: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6530: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
6540: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
6590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65b0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
65c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65d0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
65e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6620: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6660: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
6670: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6680: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
6690: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
66a0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
66b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
66d0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
66e0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
66f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6700: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6710: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6720: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6740: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6750: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
6760: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6770: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6780: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6790: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
67a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
67d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6820: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
6870: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
6880: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6890: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
68b0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
68c0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
68d0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
68e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6920: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6930: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6940: 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54  TE_OPEN_FILEPROT
6950: 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20  ECTION_MASK     
6960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6970: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6980: 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72  700000../* Reser
6990: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
69a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
69b0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
69c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
69d0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
69e0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
69f0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6a00: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6a10: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6a20: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6a30: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6a40: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6a50: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6a60: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6a70: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6a80: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6a90: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6aa0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6ab0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6ac0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6ad0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6ae0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
6af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b00: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6b10: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6b20: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6b30: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6b40: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6b50: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6b60: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6b70: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6b80: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6b90: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6ba0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6bb0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6bc0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6bd0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6be0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
6bf0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6c00: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6c10: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6c20: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6c30: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6c40: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6c50: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6c60: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6c70: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6c80: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6c90: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6ca0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6cb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6cc0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6cd0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6ce0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
6cf0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6d00: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6d10: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6d20: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6d30: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6d40: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6d50: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6d60: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6d70: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6d80: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6d90: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6da0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6db0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6dc0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6dd0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6de0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
6df0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6e00: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6e10: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6e20: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6e30: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6e40: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6e50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6e60: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6e70: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6e80: 69 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69  icates that a fi
6e90: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6ea0: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6eb0: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6ec0: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6ed0: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6ee0: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6ef0: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6f00: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
6f10: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
6f20: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
6f30: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
6f40: 69 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20  ivileges..**.** 
6f50: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6f60: 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72  _BATCH_ATOMIC pr
6f70: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6f80: 74 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  t the underlying
6f90: 0a 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 73  .** filesystem s
6fa0: 75 70 70 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75  upports doing mu
6fb0: 6c 74 69 70 6c 65 20 77 72 69 74 65 20 6f 70 65  ltiple write ope
6fc0: 72 61 74 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c  rations atomical
6fd0: 6c 79 20 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a  ly when those.**
6fe0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
6ff0: 73 20 61 72 65 20 62 72 61 63 6b 65 74 65 64 20  s are bracketed 
7000: 62 79 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  by [SQLITE_FCNTL
7010: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
7020: 49 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c  ITE] and.** [SQL
7030: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
7040: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a  _ATOMIC_WRITE]..
7050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7060: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
7070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7080: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
7090: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
70a0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
70b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
70c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
70d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
70e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
70f0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
7100: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7110: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
7120: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
7130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7140: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
7150: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7160: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
7170: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7180: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
7190: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
71a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
71b0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
71c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
71d0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
71e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
71f0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
7200: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
7210: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7220: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
7230: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
7240: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7250: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
7260: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
7270: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
7280: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
7290: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
72a0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
72b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
72c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
72d0: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
72e0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
72f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
7300: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
7310: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
7320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7330: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
7340: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7350: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
7360: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
7370: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
7380: 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a   0x00004000../*.
7390: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
73a0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
73b0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
73c0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
73d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
73e0: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
73f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
7400: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
7410: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
7420: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
7430: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
7440: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7450: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
7460: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
7470: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
7480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7490: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
74b0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
74c0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
74d0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
74e0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
74f0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
7500: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
7510: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
7520: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
7530: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
7540: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
7550: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
7560: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
7570: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7580: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
7590: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
75a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
75b0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
75c0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
75d0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
75e0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
75f0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
7600: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
7610: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
7620: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
7630: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
7640: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
7650: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
7660: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
7670: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
7680: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
7690: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
76a0: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
76b0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
76c0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
76d0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
76e0: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
76f0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7700: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
7710: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
7720: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
7730: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
7740: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
7750: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
7760: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
7770: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
7780: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7790: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
77a0: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
77b0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
77c0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
77d0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
77e0: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
77f0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
7800: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
7810: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
7820: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
7830: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
7840: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
7850: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
7860: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
7870: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
7880: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7890: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
78a0: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
78b0: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
78c0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
78d0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
78e0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
78f0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
7900: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
7910: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
7920: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
7930: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
7940: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
7950: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
7960: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
7970: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
7980: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
7990: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
79a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
79b0: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
79c0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
79d0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
79e0: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
79f0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
7a00: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
7a10: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
7a20: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7a30: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
7a40: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
7a50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7a60: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
7a70: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
7a80: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7a90: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
7aa0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
7ab0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7ac0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
7ad0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
7ae0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7af0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
7b00: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
7b10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
7b20: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
7b30: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
7b40: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
7b50: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
7b60: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
7b70: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
7b80: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
7b90: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
7ba0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
7bb0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
7bc0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
7bd0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
7be0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7bf0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
7c00: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
7c10: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
7c20: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
7c30: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
7c40: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
7c50: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7c60: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
7c70: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
7c80: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
7c90: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
7ca0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7cb0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
7cc0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
7cd0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
7ce0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7cf0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
7d00: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
7d10: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
7d20: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
7d30: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7d40: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7d50: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
7d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7d70: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
7d80: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
7d90: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
7da0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7db0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
7dc0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
7dd0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
7de0: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
7df0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
7e00: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
7e10: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
7e20: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
7e30: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
7e40: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
7e50: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7e60: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
7e70: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
7e80: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7e90: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
7ea0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7eb0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
7ec0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
7ed0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
7ee0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
7ef0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
7f00: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
7f10: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
7f20: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7f30: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
7f40: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
7f50: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
7f60: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
7f70: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
7f80: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
7f90: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7fa0: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
7fb0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7fc0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
7fd0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7fe0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
7ff0: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
8000: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8010: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
8020: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
8030: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
8040: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
8050: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
8060: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
8070: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
8080: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
8090: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
80a0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
80b0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
80c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
80d0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
80e0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
80f0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
8100: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
8110: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
8120: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
8130: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
8140: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
8150: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
8160: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
8170: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
8180: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8190: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
81a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
81b0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
81c0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
81d0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
81e0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
81f0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
8200: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
8210: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
8220: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
8230: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
8240: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
8250: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
8260: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
8270: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
8280: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
8290: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
82a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
82b0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
82c0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
82d0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
82e0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
82f0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
8300: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
8310: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
8320: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
8330: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
8340: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
8350: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
8360: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
8370: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
8380: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
8390: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
83a0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
83b0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
83c0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
83d0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
83e0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
83f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
8400: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
8410: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
8420: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
8430: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
8440: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
8450: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
8460: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
8470: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
8480: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
8490: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
84a0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
84b0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
84c0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
84d0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
84e0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
84f0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
8500: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
8510: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
8520: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
8530: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
8540: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
8550: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
8560: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
8570: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
8580: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
8590: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
85a0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
85b0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
85c0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
85d0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
85e0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
85f0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
8600: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
8610: 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74  .** A [file cont
8620: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69  rol opcodes | li
8630: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
8640: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
8650: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
8660: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
8670: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
8680: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8690: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
86a0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
86b0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
86c0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
86d0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
86e0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
86f0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
8700: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
8710: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
8720: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
8730: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
8740: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
8750: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
8760: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
8770: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
8780: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
8790: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
87a0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
87b0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
87c0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
87d0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
87e0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
87f0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
8800: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
8810: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
8820: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
8830: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
8840: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
8850: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
8860: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
8870: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
8880: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8890: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
88a0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
88b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
88c0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
88d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
88e0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
88f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8900: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
8910: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8920: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
8930: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8940: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
8950: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8960: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
8970: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8980: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
8990: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
89a0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
89b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
89c0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
89d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
89e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
89f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8a00: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
8a10: 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c  _WHEN_OPEN].** <
8a20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8a30: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
8a40: 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  WRITE].** <li> [
8a50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
8a60: 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  UTABLE].** <li> 
8a70: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41  [SQLITE_IOCAP_BA
8a80: 54 43 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  TCH_ATOMIC].** <
8a90: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
8aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8ab0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
8ac0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
8ad0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
8ae0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8b00: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
8b10: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
8b20: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
8b30: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
8b40: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
8b50: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
8b60: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
8b70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
8b80: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
8b90: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8bb0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
8bc0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
8bd0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
8be0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
8bf0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
8c00: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
8c10: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
8c20: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
8c30: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
8c40: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
8c50: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
8c60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8c70: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8c80: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
8c90: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
8ca0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
8cb0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
8cc0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
8cd0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
8ce0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
8cf0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
8d00: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
8d10: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
8d20: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
8d30: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
8d40: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
8d50: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
8d60: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8d70: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
8d80: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
8d90: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
8da0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8db0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
8dc0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
8dd0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
8de0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
8df0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8e00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
8e10: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8e20: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
8e30: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
8e40: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
8e50: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
8e60: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8e70: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
8e80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
8e90: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8ea0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8eb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8ec0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8ed0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8ee0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8ef0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8f00: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8f10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8f30: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8f40: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8f50: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
8f60: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
8f70: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8f80: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8f90: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
8fa0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
8fb0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8fc0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8fd0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8fe0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8ff0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
9000: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
9010: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
9020: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
9030: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
9040: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
9050: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
9060: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
9070: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
9080: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
9090: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
90a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
90b0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
90c0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
90d0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
90e0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
90f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
9100: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
9110: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
9120: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
9130: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
9140: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
9150: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
9160: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
9170: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
9180: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
9190: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
91a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
91b0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
91c0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
91d0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
91e0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74  rsion 2 */.  int
91f0: 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74   (*xFetch)(sqlit
9200: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
9210: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69  3_int64 iOfst, i
9220: 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a  nt iAmt, void **
9230: 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  pp);.  int (*xUn
9240: 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  fetch)(sqlite3_f
9250: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9260: 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20  t64 iOfst, void 
9270: 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  *p);.  /* Method
9280: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
9290: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  d for version 3 
92a0: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
92b0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
92c0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
92d0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
92e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
92f0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
9300: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
9310: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69  ** KEYWORDS: {fi
9320: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
9330: 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f  es} {file contro
9340: 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  l opcode}.**.** 
9350: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
9360: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
9370: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
9380: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
9390: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
93a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
93b0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
93c0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
93d0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
93e0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c  terface..**.** <
93f0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  ul>.** <li>[[SQL
9400: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
9410: 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ATE]].** The [SQ
9420: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
9430: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
9440: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
9450: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
9460: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
9470: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
9480: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
9490: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
94a0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
94b0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
94c0: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
94d0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
94e0: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
94f0: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
9500: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
9510: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
9520: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
9530: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
9540: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
9550: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
9560: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
9570: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
9580: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
9590: 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
95a0: 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54  e when the SQLIT
95b0: 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c  E_TEST.** compil
95c0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
95d0: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   used..**.** <li
95e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
95f0: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
9600: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9610: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
9620: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
9630: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
9640: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
9650: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
9660: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
9670: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
9680: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
9690: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
96a0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
96b0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
96c0: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
96d0: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
96e0: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
96f0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
9700: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
9710: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
9720: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
9730: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
9740: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
9750: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
9760: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9770: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
9780: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
9790: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
97a0: 5f 4c 49 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20  _LIMIT]].** The 
97b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
97c0: 5a 45 5f 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65  ZE_LIMIT] opcode
97d0: 20 69 73 20 75 73 65 64 20 62 79 20 69 6e 2d 6d   is used by in-m
97e0: 65 6d 6f 72 79 20 56 46 53 20 74 68 61 74 0a 2a  emory VFS that.*
97f0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71  * implements [sq
9800: 6c 69 74 65 33 5f 64 65 73 65 72 69 61 6c 69 7a  lite3_deserializ
9810: 65 28 29 5d 20 74 6f 20 73 65 74 20 61 6e 20 75  e()] to set an u
9820: 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68  pper bound on th
9830: 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65  e size.** of the
9840: 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
9850: 61 73 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ase.  The argume
9860: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
9870: 74 6f 20 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e  to a [sqlite3_in
9880: 74 36 34 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  t64]..** If the 
9890: 69 6e 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20  integer pointed 
98a0: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
98b0: 74 68 65 6e 20 69 74 20 69 73 20 66 69 6c 6c 65  then it is fille
98c0: 64 20 69 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  d in with the.**
98d0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20   current limit. 
98e0: 20 4f 74 68 65 72 77 69 73 65 20 74 68 65 20 6c   Otherwise the l
98f0: 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 74  imit is set to t
9900: 68 65 20 6c 61 72 67 65 72 20 6f 66 20 74 68 65  he larger of the
9910: 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
9920: 20 69 6e 74 65 67 65 72 20 70 6f 69 6e 74 65 64   integer pointed
9930: 20 74 6f 20 61 6e 64 20 74 68 65 20 63 75 72 72   to and the curr
9940: 65 6e 74 20 64 61 74 61 62 61 73 65 20 73 69 7a  ent database siz
9950: 65 2e 20 20 54 68 65 20 69 6e 74 65 67 65 72 0a  e.  The integer.
9960: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ** pointed to is
9970: 20 73 65 74 20 74 6f 20 74 68 65 20 6e 65 77 20   set to the new 
9980: 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  limit..**.** <li
9990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
99a0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
99b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
99c0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
99d0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
99e0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
99f0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
9a00: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
9a10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9a20: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
9a30: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
9a40: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
9a50: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
9a60: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
9a70: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
9a80: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
9a90: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
9aa0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
9ab0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
9ac0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
9ad0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
9ae0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
9af0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
9b00: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
9b10: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
9b20: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
9b30: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
9b40: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
9b50: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
9b60: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
9b70: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
9b80: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
9b90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9ba0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
9bb0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9bc0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
9bd0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9be0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9bf0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9c00: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9c10: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9c20: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
9c30: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9c40: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9c50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9c60: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e  OURNAL_POINTER].
9c70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9c80: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9c90: 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  L_POINTER]].** T
9ca0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9cb0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9cc0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9cd0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
9ce0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
9cf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9d00: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
9d10: 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c  with the journal
9d20: 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a   file (either.**
9d30: 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a   the [rollback j
9d40: 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b  ournal] or the [
9d50: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d  write-ahead log]
9d60: 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ) for a particul
9d70: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9d80: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9d90: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9da0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9db0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9dc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9dd0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9de0: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9df0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9e00: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9e10: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9e20: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9e30: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9e40: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9e50: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9e60: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9e70: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
9e80: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
9e90: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
9ea0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
9eb0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
9ec0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9ed0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9ee0: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9ef0: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9f00: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9f10: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9f20: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9f30: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
9f40: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9f50: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9f60: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9f70: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
9f80: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
9f90: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
9fa0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
9fb0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
9fc0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
9fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9fe0: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9ff0: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
a000: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
a010: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
a020: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
a030: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
a040: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
a050: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
a060: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
a070: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
a080: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
a090: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
a0a0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
a0b0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
a0c0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
a0d0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
a0e0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
a0f0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a100: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
a110: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
a120: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
a130: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
a140: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
a150: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
a160: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
a170: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a180: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
a190: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
a1a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
a1b0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
a1c0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
a1d0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
a1e0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
a1f0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
a200: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
a210: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
a220: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
a230: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
a240: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
a250: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
a260: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
a270: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
a280: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
a290: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
a2a0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
a2b0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
a2c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a2d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
a2e0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
a2f0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
a300: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
a310: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
a320: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
a330: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
a340: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
a350: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a360: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
a370: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a380: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
a390: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
a3a0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
a3b0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
a3c0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
a3d0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
a3e0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
a3f0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
a400: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
a410: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
a420: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
a430: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
a440: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
a450: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
a460: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
a470: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
a480: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
a490: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
a4a0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
a4b0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
a4c0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
a4d0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
a4e0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
a4f0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
a500: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
a510: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
a520: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
a530: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
a540: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
a550: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
a560: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
a570: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
a580: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
a590: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
a5a0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
a5b0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
a5c0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
a5d0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
a5e0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
a5f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
a600: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
a610: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
a620: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
a630: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
a640: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
a650: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
a660: 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  st integer is th
a670: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
a680: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
a690: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
a6a0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
a6b0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
a6c0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
a6d0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
a6e0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
a6f0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
a700: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
a710: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
a720: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
a730: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
a740: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
a750: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
a760: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
a770: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
a780: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
a790: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
a7a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a7b0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
a7c0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a7d0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a7e0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
a7f0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a800: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a810: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
a820: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
a830: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
a840: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
a850: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
a860: 20 6c 6f 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d   log ([WAL file]
a870: 29 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  ) and shared mem
a880: 6f 72 79 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65  ory.** files use
a890: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
a8a0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
a8b0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
a8c0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
a8d0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
a8e0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a8f0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a900: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a910: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a920: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a930: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a940: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a950: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a960: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a970: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a980: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a990: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a9a0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a9b0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a9c0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a9d0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a9e0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a9f0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
aa00: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
aa10: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
aa20: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
aa30: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
aa40: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
aa50: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
aa60: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
aa70: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
aa80: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
aa90: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
aaa0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
aab0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
aac0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
aad0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
aae0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
aaf0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
ab00: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
ab10: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
ab20: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
ab30: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
ab40: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
ab50: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
ab60: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
ab70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab80: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
ab90: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
aba0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
abb0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
abc0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
abd0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
abe0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
abf0: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
ac00: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
ac10: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
ac20: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
ac30: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
ac40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
ac50: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
ac60: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
ac70: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
ac80: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
ac90: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
aca0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
acb0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
acc0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
acd0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
ace0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
acf0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
ad00: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
ad10: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
ad20: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
ad30: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
ad40: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
ad50: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
ad60: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
ad70: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
ad80: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
ad90: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
ada0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
adb0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
adc0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
add0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ade0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
adf0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
ae00: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
ae10: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
ae20: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
ae30: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
ae40: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
ae50: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
ae60: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
ae70: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
ae80: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
ae90: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
aea0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
aeb0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
aec0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
aed0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
aee0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
aef0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
af00: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
af10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
af20: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
af30: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
af40: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
af50: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
af60: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
af70: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
af80: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
af90: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
afa0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
afb0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
afc0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
afd0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
afe0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
aff0: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
b000: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
b010: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
b020: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
b030: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
b040: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
b050: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
b060: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
b070: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
b080: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
b090: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
b0a0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
b0b0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
b0c0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
b0d0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
b0e0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
b0f0: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
b100: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
b110: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
b120: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
b130: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
b140: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
b150: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
b160: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
b170: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
b180: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
b190: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
b1a0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
b1b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b1c0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b1d0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
b1e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
b1f0: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
b200: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
b210: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
b220: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
b230: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
b240: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
b250: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
b260: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
b270: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
b280: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
b290: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
b2a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
b2b0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
b2c0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
b2d0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
b2e0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
b2f0: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
b300: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
b310: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
b320: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
b330: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
b340: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
b350: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
b360: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b370: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
b380: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
b390: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
b3a0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
b3b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b3c0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
b3d0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
b3e0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
b3f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
b400: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
b410: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b420: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
b430: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
b440: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
b450: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
b460: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b470: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b480: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
b490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
b4a0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
b4b0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
b4c0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
b4d0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
b4e0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
b4f0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
b500: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
b510: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
b520: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
b530: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
b540: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
b550: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
b560: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
b570: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b580: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b590: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
b5a0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
b5b0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
b5c0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
b5d0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
b5e0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
b5f0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
b600: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
b610: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
b620: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
b630: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
b640: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
b650: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
b660: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
b670: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
b680: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
b690: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b6a0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
b6b0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
b6c0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
b6d0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
b6e0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
b6f0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
b700: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b710: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
b720: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
b730: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
b740: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
b750: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
b760: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
b770: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
b780: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
b790: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
b7a0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
b7b0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
b7c0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
b7d0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
b7e0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
b7f0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
b800: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
b810: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
b820: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b830: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b840: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
b850: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
b860: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b870: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
b880: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
b890: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
b8a0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
b8b0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
b8c0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
b8d0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
b8e0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b8f0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b900: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b910: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b920: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b930: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b940: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b950: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b960: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b970: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b980: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b990: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b9a0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b9b0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b9c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b9d0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b9e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b9f0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
ba00: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
ba10: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
ba20: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
ba30: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
ba40: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
ba50: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
ba60: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
ba70: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
ba80: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
ba90: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
baa0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
bab0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
bac0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
bad0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
bae0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
baf0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
bb00: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
bb10: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
bb20: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
bb30: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
bb40: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
bb50: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
bb60: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
bb70: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
bb80: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
bb90: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
bba0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
bbb0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
bbc0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
bbd0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
bbe0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
bbf0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
bc00: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
bc10: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
bc20: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
bc30: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
bc40: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
bc50: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
bc60: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
bc70: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
bc80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
bc90: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
bca0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
bcb0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
bcc0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
bcd0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
bce0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
bcf0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
bd00: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
bd10: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
bd20: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
bd30: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
bd40: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
bd50: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
bd60: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
bd70: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
bd80: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
bd90: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
bda0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
bdb0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
bdc0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
bdd0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
bde0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
bdf0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
be00: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
be10: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
be20: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
be30: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
be40: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
be50: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
be60: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
be70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
be80: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
be90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
bea0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
beb0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
bec0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
bed0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
bee0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
bef0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
bf00: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
bf10: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
bf20: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
bf30: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
bf40: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
bf50: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
bf60: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
bf70: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
bf80: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
bf90: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
bfa0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
bfb0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
bfc0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
bfd0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
bfe0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
bff0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
c000: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
c010: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
c020: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
c030: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
c040: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
c050: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
c060: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
c070: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
c080: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
c090: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
c0a0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
c0b0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
c0c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c0d0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
c0e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c0f0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
c100: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
c110: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
c120: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
c130: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
c140: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
c150: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
c160: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
c170: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
c180: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
c190: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
c1a0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
c1b0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
c1c0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
c1d0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
c1e0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
c1f0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
c200: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
c210: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
c220: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
c230: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
c240: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
c250: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
c260: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
c270: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
c280: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c290: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
c2a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c2b0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
c2c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
c2d0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
c2e0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
c2f0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
c300: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
c310: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
c320: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
c330: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
c340: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
c350: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
c360: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
c370: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
c380: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
c390: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
c3a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c3b0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
c3c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c3d0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c3e0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
c3f0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
c400: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
c410: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
c420: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
c430: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
c440: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
c450: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
c460: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
c470: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
c480: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
c490: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
c4a0: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
c4b0: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
c4c0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
c4d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c4e0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
c4f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c500: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c510: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
c520: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
c530: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
c540: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
c550: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
c560: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
c570: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
c580: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
c590: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
c5a0: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
c5b0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
c5c0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
c5d0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
c5e0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
c5f0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
c600: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
c610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
c620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
c630: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
c640: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
c650: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
c660: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
c670: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
c680: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
c690: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
c6a0: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
c6b0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
c6c0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
c6d0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
c6e0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
c6f0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
c700: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
c710: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
c720: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
c730: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
c740: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
c750: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
c760: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
c770: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
c780: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
c790: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
c7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
c7b0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
c7c0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c7d0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
c7e0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
c7f0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
c800: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
c810: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c820: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
c830: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
c840: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c850: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
c860: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c870: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
c880: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
c890: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
c8a0: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
c8b0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
c8c0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
c8d0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
c8e0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
c8f0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
c900: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c910: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c920: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
c930: 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   If the [SQLITE_
c940: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c950: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
c960: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
c970: 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  OK, then.** the 
c980: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
c990: 69 73 20 70 6c 61 63 65 64 20 69 6e 20 22 62 61  is placed in "ba
c9a0: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 22 2c  tch write mode",
c9b0: 20 77 68 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20   which.** means 
c9c0: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77  all subsequent w
c9d0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
c9e0: 77 69 6c 6c 20 62 65 20 64 65 66 65 72 72 65 64  will be deferred
c9f0: 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f   and done.** ato
ca00: 6d 69 63 61 6c 6c 79 20 61 74 20 74 68 65 20 6e  mically at the n
ca10: 65 78 74 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ext [SQLITE_FCNT
ca20: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
ca30: 57 52 49 54 45 5d 2e 20 20 53 79 73 74 65 6d 73  WRITE].  Systems
ca40: 0a 2a 2a 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  .** that do not 
ca50: 73 75 70 70 6f 72 74 20 62 61 74 63 68 20 61 74  support batch at
ca60: 6f 6d 69 63 20 77 72 69 74 65 73 20 77 69 6c 6c  omic writes will
ca70: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
ca80: 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c  OTFOUND..** ^Fol
ca90: 6c 6f 77 69 6e 67 20 61 20 73 75 63 63 65 73 73  lowing a success
caa0: 66 75 6c 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ful SQLITE_FCNTL
cab0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
cac0: 49 54 45 20 61 6e 64 20 70 72 69 6f 72 20 74 6f  ITE and prior to
cad0: 0a 2a 2a 20 74 68 65 20 63 6c 6f 73 69 6e 67 20  .** the closing 
cae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
caf0: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
cb00: 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  E] or.** [SQLITE
cb10: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
cb20: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53  ATOMIC_WRITE], S
cb30: 51 4c 69 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a  QLite will make.
cb40: 2a 2a 20 6e 6f 20 56 46 53 20 69 6e 74 65 72 66  ** no VFS interf
cb50: 61 63 65 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65  ace calls on the
cb60: 20 73 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66   same [sqlite3_f
cb70: 69 6c 65 5d 20 66 69 6c 65 20 64 65 73 63 72 69  ile] file descri
cb80: 70 74 6f 72 0a 2a 2a 20 65 78 63 65 70 74 20 66  ptor.** except f
cb90: 6f 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  or calls to the 
cba0: 78 57 72 69 74 65 20 6d 65 74 68 6f 64 20 61 6e  xWrite method an
cbb0: 64 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  d the xFileContr
cbc0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74  ol method.** wit
cbd0: 68 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  h [SQLITE_FCNTL_
cbe0: 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a  SIZE_HINT]..**.*
cbf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
cc00: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
cc10: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68  IC_WRITE]].** Th
cc20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
cc30: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
cc40: 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75 73  ITE] opcode caus
cc50: 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20  es all write.** 
cc60: 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63 65  operations since
cc70: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 75   the previous su
cc80: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
cc90: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e   .** [SQLITE_FCN
cca0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
ccb0: 57 52 49 54 45 5d 20 74 6f 20 62 65 20 70 65 72  WRITE] to be per
ccc0: 66 6f 72 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c  formed atomicall
ccd0: 79 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  y..** This file 
cce0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
ccf0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61  [SQLITE_OK] if a
cd00: 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 77  nd only if the w
cd10: 72 69 74 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c  rites were.** al
cd20: 6c 20 70 65 72 66 6f 72 6d 65 64 20 73 75 63 63  l performed succ
cd30: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 68 61 76  essfully and hav
cd40: 65 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  e been committed
cd50: 20 74 6f 20 70 65 72 73 69 73 74 65 6e 74 20 73   to persistent s
cd60: 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61  torage..** ^Rega
cd70: 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
cd80: 72 20 6f 72 20 6e 6f 74 20 69 74 20 69 73 20 73  r or not it is s
cd90: 75 63 63 65 73 73 66 75 6c 2c 20 74 68 69 73 20  uccessful, this 
cda0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b  file control tak
cdb0: 65 73 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64  es.** the file d
cdc0: 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f 66  escriptor out of
cdd0: 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f 64   batch write mod
cde0: 65 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75  e so that all su
cdf0: 62 73 65 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74  bsequent.** writ
ce00: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  e operations are
ce10: 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a   independent..**
ce20: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
ce30: 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54  ver invoke SQLIT
ce40: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
ce50: 54 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68  TOMIC_WRITE with
ce60: 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73  out.** a prior s
ce70: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
ce80: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
ce90: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cea0: 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  TE]..**.** <li>[
ceb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f  [SQLITE_FCNTL_RO
cec0: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
ced0: 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ITE]].** The [SQ
cee0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
cef0: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
cf00: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  ] opcode causes 
cf10: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65  all write.** ope
cf20: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68  rations since th
cf30: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65  e previous succe
cf40: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
cf50: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
cf60: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cf70: 54 45 5d 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64  TE] to be rolled
cf80: 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20   back..** ^This 
cf90: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b  file control tak
cfa0: 65 73 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  es the file desc
cfb0: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61  riptor out of ba
cfc0: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a  tch write mode.*
cfd0: 2a 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75  * so that all su
cfe0: 62 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f  bsequent write o
cff0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e  perations are in
d000: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53  dependent..** ^S
d010: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
d020: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46   invoke SQLITE_F
d030: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
d040: 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f  OMIC_WRITE witho
d050: 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75  ut.** a prior su
d060: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
d070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
d080: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
d090: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  E]..**.** <li>[[
d0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
d0b0: 4b 5f 54 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54  K_TIMEOUT]].** T
d0c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d0d0: 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f  _LOCK_TIMEOUT] o
d0e0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 74 74  pcode causes att
d0f0: 65 6d 70 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a  empts to obtain.
d100: 2a 2a 20 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75  ** a file lock u
d110: 73 69 6e 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f  sing the xLock o
d120: 72 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  r xShmLock metho
d130: 64 73 20 6f 66 20 74 68 65 20 56 46 53 20 74 6f  ds of the VFS to
d140: 20 77 61 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20   wait.** for up 
d150: 74 6f 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  to M millisecond
d160: 73 20 62 65 66 6f 72 65 20 66 61 69 6c 69 6e 67  s before failing
d170: 2c 20 77 68 65 72 65 20 4d 20 69 73 20 74 68 65  , where M is the
d180: 20 73 69 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69   single .** unsi
d190: 67 6e 65 64 20 69 6e 74 65 67 65 72 20 70 61 72  gned integer par
d1a0: 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ameter..**.** <l
d1b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d1c0: 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a  _DATA_VERSION]].
d1d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d1e0: 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f  CNTL_DATA_VERSIO
d1f0: 4e 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  N] opcode is use
d200: 64 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  d to detect chan
d210: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61  ges to.** a data
d220: 62 61 73 65 20 66 69 6c 65 2e 20 20 54 68 65 20  base file.  The 
d230: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
d240: 69 6e 74 65 72 20 74 6f 20 61 20 33 32 2d 62 69  inter to a 32-bi
d250: 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
d260: 65 72 2e 0a 2a 2a 20 54 68 65 20 22 64 61 74 61  er..** The "data
d270: 20 76 65 72 73 69 6f 6e 22 20 66 6f 72 20 74 68   version" for th
d280: 65 20 70 61 67 65 72 20 69 73 20 77 72 69 74 74  e pager is writt
d290: 65 6e 20 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e  en into the poin
d2a0: 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61  ter.  The.** "da
d2b0: 74 61 20 76 65 72 73 69 6f 6e 22 20 63 68 61 6e  ta version" chan
d2c0: 67 65 73 20 77 68 65 6e 65 76 65 72 20 61 6e 79  ges whenever any
d2d0: 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73 20 74   change occurs t
d2e0: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
d2f0: 69 6e 67 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ing.** database 
d300: 66 69 6c 65 2c 20 65 69 74 68 65 72 20 74 68 72  file, either thr
d310: 6f 75 67 68 20 53 51 4c 20 73 74 61 74 65 6d 65  ough SQL stateme
d320: 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  nts on the same 
d330: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
d340: 65 63 74 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67  ection or throug
d350: 68 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  h transactions c
d360: 6f 6d 6d 69 74 74 65 64 20 62 79 20 73 65 70 61  ommitted by sepa
d370: 72 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  rate database.**
d380: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73   connections pos
d390: 73 69 62 6c 79 20 69 6e 20 6f 74 68 65 72 20 70  sibly in other p
d3a0: 72 6f 63 65 73 73 65 73 2e 20 54 68 65 20 5b 73  rocesses. The [s
d3b0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
d3c0: 6e 67 65 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  nges()].** inter
d3d0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
d3e0: 20 74 6f 20 66 69 6e 64 20 69 66 20 61 6e 79 20   to find if any 
d3f0: 64 61 74 61 62 61 73 65 20 6f 6e 20 74 68 65 20  database on the 
d400: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 63  connection has c
d410: 68 61 6e 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74  hanged,.** but t
d420: 68 61 74 20 69 6e 74 65 72 66 61 63 65 20 72 65  hat interface re
d430: 73 70 6f 6e 64 73 20 74 6f 20 63 68 61 6e 67 65  sponds to change
d440: 73 20 6f 6e 20 54 45 4d 50 20 61 73 20 77 65 6c  s on TEMP as wel
d450: 6c 20 61 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f  l as MAIN and do
d460: 65 73 0a 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64  es.** not provid
d470: 65 20 61 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f  e a mechanism to
d480: 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20   detect changes 
d490: 74 6f 20 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41  to MAIN only.  A
d4a0: 6c 73 6f 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  lso, the.** [sql
d4b0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
d4c0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
d4d0: 72 65 73 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65  responds to inte
d4e0: 72 6e 61 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c  rnal changes onl
d4f0: 79 20 61 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63  y and.** omits c
d500: 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 20 6f  hanges made by o
d510: 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f  ther database co
d520: 6e 6e 65 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  nnections.  The.
d530: 2a 2a 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f  ** [PRAGMA data_
d540: 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64  version] command
d550: 20 70 72 6f 76 69 64 65 20 61 20 6d 65 63 68 61   provide a mecha
d560: 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63  nism to detect c
d570: 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73  hanges to.** a s
d580: 69 6e 67 6c 65 20 61 74 74 61 63 68 65 64 20 64  ingle attached d
d590: 61 74 61 62 61 73 65 20 74 68 61 74 20 6f 63 63  atabase that occ
d5a0: 75 72 20 64 75 65 20 74 6f 20 6f 74 68 65 72 20  ur due to other 
d5b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d5c0: 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69  ions,.** but omi
d5d0: 74 73 20 63 68 61 6e 67 65 73 20 69 6d 70 6c 65  ts changes imple
d5e0: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 64 61  mented by the da
d5f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d600: 6e 20 6f 6e 20 77 68 69 63 68 20 69 74 20 69 73  n on which it is
d610: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 54 68 69  .** called.  Thi
d620: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
d630: 73 20 74 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61  s the only mecha
d640: 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63  nism to detect c
d650: 68 61 6e 67 65 73 20 74 68 61 74 0a 2a 2a 20 68  hanges that.** h
d660: 61 70 70 65 6e 20 65 69 74 68 65 72 20 69 6e 74  appen either int
d670: 65 72 6e 61 6c 6c 79 20 6f 72 20 65 78 74 65 72  ernally or exter
d680: 6e 61 6c 6c 79 20 61 6e 64 20 74 68 61 74 20 61  nally and that a
d690: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
d6a0: 74 68 0a 2a 2a 20 61 20 70 61 72 74 69 63 75 6c  th.** a particul
d6b0: 61 72 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ar attached data
d6c0: 62 61 73 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  base..** </ul>.*
d6d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d6e0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
d6f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
d700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d710: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
d720: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a  OXYFILE       2.
d730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d740: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
d750: 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23  XYFILE       3.#
d760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d770: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  NTL_LAST_ERRNO  
d780: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
d790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d7a0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
d7b0: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
d7c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d7d0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
d7e0: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
d7f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d800: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
d810: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
d820: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d830: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
d840: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
d850: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
d860: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
d870: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
d880: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
d890: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
d8a0: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
d8b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
d8c0: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
d8d0: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
d8e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
d8f0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
d900: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
d910: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
d920: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
d930: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
d940: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
d950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d960: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
d970: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
d980: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
d990: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
d9a0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
d9b0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
d9c0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
d9d0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
d9e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
d9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
da00: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
da10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
da20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
da30: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20  CNTL_HAS_MOVED  
da40: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23              20.#
da50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
da60: 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20  NTL_SYNC        
da70: 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64             21.#d
da80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
da90: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
daa0: 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65  WO        22.#de
dab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dac0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
dad0: 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66  LE       23.#def
dae0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
daf0: 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20  _WAL_BLOCK      
db00: 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69          24.#defi
db10: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
db20: 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20  ZIPVFS          
db30: 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e         25.#defin
db40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
db50: 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20  BU              
db60: 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65        26.#define
db70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
db80: 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  S_POINTER       
db90: 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20       27.#define 
dba0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
dbb0: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20  RNAL_POINTER    
dbc0: 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53      28.#define S
dbd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
dbe0: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_GET_HANDLE    
dbf0: 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51     29.#define SQ
dc00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20  LITE_FCNTL_PDB  
dc10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dc20: 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    30.#define SQL
dc30: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
dc40: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
dc50: 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   31.#define SQLI
dc60: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
dc70: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
dc80: 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  32.#define SQLIT
dc90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
dca0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 33  _ATOMIC_WRITE  3
dcb0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
dcc0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45  _FCNTL_LOCK_TIME
dcd0: 4f 55 54 20 20 20 20 20 20 20 20 20 20 20 33 34  OUT           34
dce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dcf0: 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49  FCNTL_DATA_VERSI
dd00: 4f 4e 20 20 20 20 20 20 20 20 20 20 20 33 35 0a  ON           35.
dd10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dd20: 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20  CNTL_SIZE_LIMIT 
dd30: 20 20 20 20 20 20 20 20 20 20 20 20 33 36 0a 0a              36..
dd40: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61  /* deprecated na
dd50: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mes */.#define S
dd60: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
dd70: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
dd80: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
dd90: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
dda0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
ddb0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
ddc0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53    SQLITE_FCNTL_S
ddd0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
dde0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ddf0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
de00: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43         SQLITE_FC
de10: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a  NTL_LAST_ERRNO..
de20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
de30: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
de40: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
de50: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
de60: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
de70: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
de80: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
de90: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
dea0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
deb0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
dec0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
ded0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
dee0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
def0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
df00: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
df10: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
df20: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
df30: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
df40: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
df50: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
df60: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
df70: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
df80: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
df90: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
dfa0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
dfb0: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20  I3REF: Loadable 
dfc0: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a  Extension Thunk.
dfd0: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
dfe0: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71  to the opaque sq
dff0: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
e000: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  es structure is 
e010: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
e020: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
e030: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73   to entry points
e040: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78   of [loadable ex
e050: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73  tensions].  This
e060: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75  .** structure mu
e070: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20  st be typedefed 
e080: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b  in order to work
e090: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72   around compiler
e0a0: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20   warnings.** on 
e0b0: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a  some platforms..
e0c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e0d0: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
e0e0: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61  utines sqlite3_a
e0f0: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a  pi_routines;../*
e100: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
e110: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
e120: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
e130: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
e140: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
e150: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
e160: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
e170: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
e180: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
e190: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
e1a0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
e1b0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
e1c0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
e1d0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
e1e0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
e1f0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
e200: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
e210: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
e220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
e230: 2a 2a 20 54 68 65 20 56 46 53 20 69 6e 74 65 72  ** The VFS inter
e240: 66 61 63 65 20 69 73 20 73 6f 6d 65 74 69 6d 65  face is sometime
e250: 73 20 65 78 74 65 6e 64 65 64 20 62 79 20 61 64  s extended by ad
e260: 64 69 6e 67 20 6e 65 77 20 6d 65 74 68 6f 64 73  ding new methods
e270: 20 6f 6e 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64   onto.** the end
e280: 2e 20 20 45 61 63 68 20 74 69 6d 65 20 73 75 63  .  Each time suc
e290: 68 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f  h an extension o
e2a0: 63 63 75 72 73 2c 20 74 68 65 20 69 56 65 72 73  ccurs, the iVers
e2b0: 69 6f 6e 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20  ion field.** is 
e2c0: 69 6e 63 72 65 6d 65 6e 74 65 64 2e 20 20 54 68  incremented.  Th
e2d0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
e2e0: 20 73 74 61 72 74 65 64 20 6f 75 74 20 61 73 20   started out as 
e2f0: 31 20 69 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b  1 in.** SQLite [
e300: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f  version 3.5.0] o
e310: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d  n [dateof:3.5.0]
e320: 2c 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65 64  , then increased
e330: 20 74 6f 20 32 0a 2a 2a 20 77 69 74 68 20 53 51   to 2.** with SQ
e340: 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e  Lite [version 3.
e350: 37 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a  7.0] on [dateof:
e360: 33 2e 37 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e  3.7.0], and then
e370: 20 69 6e 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f   increased.** to
e380: 20 33 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b   3 with SQLite [
e390: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f  version 3.7.6] o
e3a0: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d  n [dateof:3.7.6]
e3b0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
e3c0: 65 6c 64 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61  elds.** may be a
e3d0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65 20 73  ppended to the s
e3e0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e3f0: 74 20 61 6e 64 20 74 68 65 20 69 56 65 72 73 69  t and the iVersi
e400: 6f 6e 20 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20  on value.** may 
e410: 69 6e 63 72 65 61 73 65 20 61 67 61 69 6e 20 69  increase again i
e420: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
e430: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
e440: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
e450: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
e460: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
e470: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
e480: 74 68 65 20 74 72 61 6e 73 69 74 69 6f 6e 20 66  the transition f
e490: 72 6f 6d 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76  rom.** SQLite [v
e4a0: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f  ersion 3.5.9] to
e4b0: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d   [version 3.6.0]
e4c0: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e   on [dateof:3.6.
e4d0: 30 5d 0a 2a 2a 20 61 6e 64 20 79 65 74 20 74 68  0].** and yet th
e4e0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
e4f0: 20 77 61 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65   was not modifie
e500: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
e510: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
e520: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
e530: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
e540: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
e550: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
e560: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
e570: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
e580: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
e590: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
e5a0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
e5b0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
e5c0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
e5d0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
e5e0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
e5f0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
e600: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
e610: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
e620: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
e630: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
e640: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
e650: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
e660: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
e670: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
e680: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
e690: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
e6a0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
e6b0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
e6c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
e6d0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
e6e0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
e6f0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
e700: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
e710: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
e720: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
e730: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
e740: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
e750: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
e760: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
e770: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
e780: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
e790: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
e7a0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
e7b0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
e7c0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
e7d0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
e7e0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
e7f0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
e800: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
e810: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
e820: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
e830: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
e840: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
e850: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
e860: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
e870: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
e880: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
e890: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
e8a0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
e8b0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
e8c0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
e8d0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
e8e0: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
e8f0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e900: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
e910: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
e920: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
e930: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
e940: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
e950: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
e960: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
e970: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
e980: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
e990: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
e9a0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
e9b0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
e9c0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
e9d0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
e9e0: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
e9f0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
ea00: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
ea10: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
ea20: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
ea30: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
ea40: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
ea50: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
ea60: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
ea70: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
ea80: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
ea90: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
eaa0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
eab0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
eac0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
ead0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
eae0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
eaf0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
eb00: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
eb10: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
eb20: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
eb30: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
eb40: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
eb50: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
eb60: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
eb70: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
eb80: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
eb90: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
eba0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
ebb0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
ebc0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
ebd0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
ebe0: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
ebf0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
ec00: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
ec10: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
ec20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
ec30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
ec40: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
ec50: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
ec60: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
ec70: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
ec80: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
ec90: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
eca0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
ecb0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
ecc0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
ecd0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
ece0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
ecf0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
ed00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
ed10: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
ed20: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
ed30: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
ed40: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
ed50: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
ed60: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
ed70: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
ed80: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
ed90: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
eda0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
edb0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
edc0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
edd0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
ede0: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
edf0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
ee00: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
ee10: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
ee20: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee30: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
ee40: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ee50: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
ee60: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ee70: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
ee80: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
ee90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
eea0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
eeb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
eec0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
eed0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
eee0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
eef0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ef00: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
ef10: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
ef20: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
ef30: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
ef40: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
ef50: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
ef60: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
ef70: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
ef80: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
ef90: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
efa0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
efb0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
efc0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
efd0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
efe0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
eff0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
f000: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
f010: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
f020: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
f030: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
f040: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
f050: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
f060: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
f070: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
f080: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
f090: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
f0a0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
f0b0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
f0c0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
f0d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
f0e0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
f0f0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
f100: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
f110: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
f120: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
f130: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
f140: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
f150: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
f160: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
f170: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
f180: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
f190: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
f1a0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
f1b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
f1c0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
f1d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
f1e0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
f1f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
f200: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
f210: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
f220: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
f230: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
f240: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
f250: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
f260: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f270: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
f280: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
f290: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
f2a0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
f2b0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
f2c0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
f2d0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
f2e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
f2f0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
f300: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
f310: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
f320: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
f330: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
f340: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
f350: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
f360: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
f370: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
f380: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
f390: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
f3a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
f3b0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
f3c0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
f3d0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
f3e0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
f3f0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
f400: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
f410: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
f420: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
f430: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
f440: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
f450: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
f460: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
f470: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
f480: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
f490: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
f4a0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
f4b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
f4c0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
f4d0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
f4e0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
f4f0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
f500: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
f510: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
f520: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
f530: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
f540: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
f550: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
f560: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
f570: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
f580: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
f590: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
f5a0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
f5b0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
f5c0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
f5d0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
f5e0: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
f5f0: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
f600: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
f610: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
f620: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
f630: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
f640: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
f650: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
f660: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
f670: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
f680: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
f690: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
f6a0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
f6b0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
f6c0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
f6d0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
f6e0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
f6f0: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
f700: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
f710: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
f720: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
f730: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f740: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
f750: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
f760: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
f770: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f780: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
f790: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
f7a0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
f7b0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
f7c0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
f7d0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
f7e0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f7f0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
f800: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
f810: 5f 41 43 43 45 53 53 5f 52 45 41 44 0a 2a 2a 20  _ACCESS_READ.** 
f820: 66 6c 61 67 20 69 73 20 6e 65 76 65 72 20 61 63  flag is never ac
f830: 74 75 61 6c 6c 79 20 75 73 65 64 20 61 6e 64 20  tually used and 
f840: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
f850: 65 64 20 69 6e 20 74 68 65 20 62 75 69 6c 74 2d  ed in the built-
f860: 69 6e 0a 2a 2a 20 56 46 53 65 73 20 6f 66 20 53  in.** VFSes of S
f870: 51 4c 69 74 65 2e 20 20 54 68 65 20 66 69 6c 65  QLite.  The file
f880: 20 69 73 20 6e 61 6d 65 64 20 62 79 20 74 68 65   is named by the
f890: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f8a0: 20 61 6e 64 20 63 61 6e 20 62 65 20 61 0a 2a 2a   and can be a.**
f8b0: 20 64 69 72 65 63 74 6f 72 79 2e 20 54 68 65 20   directory. The 
f8c0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 72  xAccess method r
f8d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
f8e0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
f8f0: 20 73 6f 6d 65 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72   some.** non-zer
f900: 6f 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 20  o error code if 
f910: 74 68 65 72 65 20 69 73 20 61 6e 20 49 2f 4f 20  there is an I/O 
f920: 65 72 72 6f 72 20 6f 72 20 69 66 20 74 68 65 20  error or if the 
f930: 6e 61 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66  name of.** the f
f940: 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  ile given in the
f950: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f960: 20 69 73 20 69 6c 6c 65 67 61 6c 2e 20 20 49 66   is illegal.  If
f970: 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 69 73   SQLITE_OK.** is
f980: 20 72 65 74 75 72 6e 65 64 2c 20 74 68 65 6e 20   returned, then 
f990: 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 20 7a 65 72 6f  non-zero or zero
f9a0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
f9b0: 20 2a 70 52 65 73 4f 75 74 20 74 6f 20 69 6e 64   *pResOut to ind
f9c0: 69 63 61 74 65 0a 2a 2a 20 77 68 65 74 68 65 72  icate.** whether
f9d0: 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   or not the file
f9e0: 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 2e 20   is accessible. 
f9f0: 20 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20   .**.** ^SQLite 
fa00: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
fa10: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
fa20: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
fa30: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
fa40: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
fa50: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
fa60: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
fa70: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
fa80: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
fa90: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
faa0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
fab0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
fac0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
fad0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
fae0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
faf0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
fb00: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
fb10: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
fb20: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
fb30: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
fb40: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
fb50: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
fb60: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
fb70: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
fb80: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
fb90: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
fba0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
fbb0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
fbc0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
fbd0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
fbe0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
fbf0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
fc00: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
fc10: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
fc20: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
fc30: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
fc40: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
fc50: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
fc60: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
fc70: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
fc80: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
fc90: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
fca0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
fcb0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
fcc0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
fcd0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
fce0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
fcf0: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
fd00: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
fd10: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
fd20: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
fd30: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
fd40: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
fd50: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
fd60: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
fd70: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
fd80: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
fd90: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
fda0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
fdb0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
fdc0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
fdd0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
fde0: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
fdf0: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
fe00: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
fe10: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
fe20: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
fe30: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
fe40: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
fe50: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
fe60: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
fe70: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
fe80: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
fe90: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
fea0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
feb0: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
fec0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
fed0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
fee0: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
fef0: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
ff00: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
ff10: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
ff20: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
ff30: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
ff40: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
ff50: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
ff60: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
ff70: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
ff80: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
ff90: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
ffa0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
ffb0: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
ffc0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
ffd0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
ffe0: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
fff0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
10000 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
10010 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
10020 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
10030 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
10040 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
10050 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
10060 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
10070 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
10080 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
10090 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
100a0 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
100b0 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
100c0 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
100d0 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
100e0 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
100f0 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
10100 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
10110 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
10120 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
10130 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
10140 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
10150 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
10160 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
10170 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
10180 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
10190 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
101a0 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
101b0 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
101c0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
101d0 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
101e0 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
101f0 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
10200 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
10210 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
10220 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
10230 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
10240 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
10250 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
10260 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
10270 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
10280 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
10290 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
102a0 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
102b0 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
102c0 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
102d0 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
102e0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
102f0 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
10300 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
10310 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
10320 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
10330 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
10340 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
10350 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
10360 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
10370 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
10380 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
10390 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
103a0 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
103b0 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
103c0 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
103d0 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
103e0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
103f0 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
10400 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
10410 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
10420 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
10430 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
10440 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
10450 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
10460 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
10470 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
10480 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
10490 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
104a0 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
104b0 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
104c0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
104d0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
104e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
104f0 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
10500 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
10510 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
10520 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
10530 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
10540 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10550 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
10560 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
10570 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
10580 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10590 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
105a0 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
105b0 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
105c0 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
105d0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
105e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
105f0 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
10600 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
10610 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
10620 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10630 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
10640 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
10650 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
10660 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
10670 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
10680 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
10690 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
106a0 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
106b0 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
106c0 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
106d0 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
106e0 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
106f0 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
10700 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
10710 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
10720 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
10730 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
10740 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
10750 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
10760 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
10770 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
10780 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
10790 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
107a0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
107b0 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
107c0 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
107d0 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
107e0 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
107f0 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
10800 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
10810 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
10820 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
10830 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
10840 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
10850 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
10860 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
10870 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
10880 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
10890 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
108a0 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
108b0 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
108c0 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
108d0 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
108e0 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
108f0 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
10900 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
10910 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
10920 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10930 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
10940 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
10950 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
10960 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
10970 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
10980 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10990 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
109a0 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
109b0 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
109c0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
109d0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
109e0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
109f0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
10a00 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
10a10 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
10a20 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
10a30 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
10a40 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
10a50 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
10a60 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
10a70 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
10a80 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
10a90 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
10aa0 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
10ab0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
10ac0 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
10ad0 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
10ae0 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
10af0 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
10b00 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
10b10 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
10b20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
10b30 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
10b40 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
10b50 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
10b60 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
10b70 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
10b80 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10b90 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
10ba0 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
10bb0 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
10bc0 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10bd0 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
10be0 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
10bf0 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
10c00 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
10c10 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
10c20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10c30 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
10c40 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
10c50 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
10c60 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
10c70 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
10c80 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
10c90 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
10ca0 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
10cb0 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
10cc0 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
10cd0 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
10ce0 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
10cf0 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
10d00 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
10d10 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
10d20 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
10d30 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
10d40 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
10d50 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
10d60 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
10d70 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
10d80 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
10d90 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10da0 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
10db0 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
10dc0 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
10dd0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10de0 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
10df0 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
10e00 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
10e10 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
10e20 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
10e30 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
10e40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10e50 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
10e60 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
10e70 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
10e80 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
10e90 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
10ea0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
10eb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10ec0 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
10ed0 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
10ee0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
10ef0 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
10f00 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
10f10 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
10f20 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
10f30 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
10f40 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
10f50 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
10f60 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
10f70 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
10f80 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
10f90 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
10fa0 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
10fb0 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
10fc0 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
10fd0 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
10fe0 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
10ff0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
11000 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
11010 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
11020 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
11030 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
11040 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
11050 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
11060 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
11070 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
11080 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
11090 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
110a0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
110b0 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
110c0 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
110d0 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
110e0 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
110f0 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
11100 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
11110 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72  iven on the corr
11120 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
11130 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
11140 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
11150 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
11160 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
11170 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
11180 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
11190 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
111a0 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
111b0 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
111c0 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
111d0 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
111e0 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
111f0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
11200 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
11210 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
11220 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
11230 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
11240 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
11250 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
11260 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11270 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
11280 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
11290 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
112a0 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
112b0 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
112c0 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
112d0 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
112e0 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
112f0 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
11300 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
11310 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
11320 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
11330 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
11340 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
11350 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
11360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11370 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
11380 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
11390 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
113a0 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
113b0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
113c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
113d0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
113e0 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
113f0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
11400 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
11410 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
11420 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
11430 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
11440 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
11450 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
11460 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
11470 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
11480 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
11490 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
114a0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
114b0 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
114c0 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
114d0 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
114e0 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
114f0 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
11500 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
11510 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
11520 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
11530 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
11540 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
11550 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
11560 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
11570 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
11580 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
11590 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
115a0 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
115b0 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
115c0 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
115d0 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
115e0 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
115f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11600 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
11610 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
11620 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
11630 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
11640 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
11650 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
11660 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
11670 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
11680 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
11690 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
116a0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
116b0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
116c0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
116d0 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
116e0 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
116f0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
11700 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
11710 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
11720 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
11730 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
11740 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
11750 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
11760 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11770 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
11780 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
11790 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
117a0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
117b0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
117c0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
117d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
117e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
117f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11800 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
11810 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11820 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
11830 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
11840 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
11850 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
11860 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
11870 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
11880 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
11890 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
118a0 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
118b0 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
118c0 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
118d0 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
118e0 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
118f0 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
11900 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
11910 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
11920 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
11930 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
11940 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
11950 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
11960 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
11970 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
11980 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
11990 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
119a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
119b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
119c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
119d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
119e0 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
119f0 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
11a00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11a10 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
11a20 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
11a30 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
11a40 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
11a50 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
11a60 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
11a70 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
11a80 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
11a90 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
11aa0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
11ab0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
11ac0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11ad0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
11ae0 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
11af0 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
11b00 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
11b10 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
11b20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
11b30 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
11b40 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
11b50 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11b60 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
11b70 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
11b80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
11b90 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
11ba0 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
11bb0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
11bc0 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
11bd0 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
11be0 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
11bf0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
11c00 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
11c10 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
11c20 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
11c30 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
11c40 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11c50 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
11c60 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
11c70 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
11c80 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
11c90 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
11ca0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
11cb0 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
11cc0 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
11cd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
11ce0 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
11cf0 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
11d00 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
11d10 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
11d20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11d30 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
11d40 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
11d50 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
11d60 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
11d70 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
11d80 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11d90 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
11da0 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
11db0 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
11dc0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
11dd0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
11de0 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
11df0 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
11e00 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
11e10 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
11e20 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
11e30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11e40 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
11e50 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
11e60 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
11e70 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
11e80 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
11e90 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
11ea0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
11eb0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
11ec0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
11ed0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
11ee0 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
11ef0 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
11f00 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
11f10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11f20 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
11f30 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
11f40 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
11f50 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
11f60 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
11f70 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
11f80 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
11f90 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
11fa0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
11fb0 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
11fc0 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
11fd0 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
11fe0 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
11ff0 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
12000 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
12010 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
12020 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
12030 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
12040 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
12050 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
12060 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
12070 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
12080 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
12090 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
120a0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
120b0 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
120c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
120d0 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
120e0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
120f0 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
12100 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
12110 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
12120 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
12130 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
12140 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
12150 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12160 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
12170 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
12180 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
12190 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
121a0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
121b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
121c0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
121d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
121e0 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
121f0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
12200 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
12210 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
12220 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
12230 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
12240 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
12250 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
12260 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
12270 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
12280 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
12290 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
122a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
122b0 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
122c0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
122d0 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
122e0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
122f0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
12300 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
12310 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
12320 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
12330 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12340 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
12350 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
12360 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
12370 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
12380 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
12390 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
123a0 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
123b0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
123c0 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
123d0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
123e0 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
123f0 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
12400 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
12410 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
12420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
12430 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
12440 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
12450 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
12460 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
12470 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
12480 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
12490 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
124a0 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
124b0 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
124c0 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
124d0 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
124e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
124f0 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
12500 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
12510 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
12520 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
12530 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
12540 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
12550 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
12560 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
12570 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
12580 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
12590 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
125a0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68  eds..**.** <b>Th
125b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
125c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
125d0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
125e0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
125f0 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  ** must ensure t
12600 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
12610 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
12620 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
12630 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
12640 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
12650 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
12660 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  .</b>.**.** The 
12670 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12680 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61   interface.** ma
12690 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
126a0 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
126b0 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
126c0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
126d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
126e0 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
126f0 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
12700 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
12710 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
12720 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
12730 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
12740 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
12750 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
12760 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
12770 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
12780 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
12790 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
127a0 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
127b0 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
127c0 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
127d0 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
127e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
127f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
12800 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
12810 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
12820 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12830 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
12840 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
12850 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
12860 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
12870 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
12880 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
12890 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
128a0 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
128b0 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
128c0 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
128d0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
128e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
128f0 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
12900 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
12910 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
12920 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12930 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
12940 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
12950 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
12960 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
12970 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
12980 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
12990 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
129a0 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
129b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
129c0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
129d0 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
129e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
129f0 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
12a00 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
12a10 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
12a20 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  nections.** METH
12a30 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
12a40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
12a50 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
12a60 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
12a70 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
12a80 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
12a90 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
12aa0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
12ab0 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
12ac0 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
12ad0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
12ae0 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
12af0 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
12b00 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
12b10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
12b20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
12b30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
12b40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
12b50 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
12b60 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12b70 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
12b80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
12b90 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
12ba0 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
12bb0 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
12bc0 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
12bd0 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
12be0 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
12bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12c00 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
12c10 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
12c20 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
12c30 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
12c40 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
12c50 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
12c60 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
12c70 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
12c80 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
12c90 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
12ca0 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
12cb0 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
12cc0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
12cd0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
12ce0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
12cf0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
12d00 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
12d10 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
12d20 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
12d30 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
12d40 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
12d50 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
12d60 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
12d70 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
12d80 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12d90 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
12da0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
12db0 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
12dc0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
12dd0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
12de0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12df0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12e00 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
12e10 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
12e20 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
12e30 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
12e40 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
12e50 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
12e60 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
12e70 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12e80 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
12e90 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
12ea0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
12eb0 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
12ec0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
12ed0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
12ee0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
12ef0 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
12f00 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
12f10 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
12f20 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
12f30 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
12f40 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
12f50 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
12f60 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
12f70 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
12f80 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
12f90 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
12fa0 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
12fb0 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
12fc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12fd0 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
12fe0 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
12ff0 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
13000 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
13010 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
13020 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
13030 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
13040 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
13050 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
13060 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
13070 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
13080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13090 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
130a0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
130b0 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
130c0 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
130d0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
130e0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
130f0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
13100 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
13110 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
13120 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
13130 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
13140 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
13150 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
13160 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
13170 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
13180 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
13190 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
131a0 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
131b0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
131c0 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
131d0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
131e0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
131f0 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
13200 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
13210 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
13220 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
13230 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
13240 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
13250 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
13260 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
13270 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
13280 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
13290 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
132a0 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
132b0 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
132c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
132d0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
132e0 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
132f0 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
13300 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
13310 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
13320 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
13330 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
13340 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
13350 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
13360 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
13370 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
13380 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
13390 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
133a0 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
133b0 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
133c0 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
133d0 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
133e0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
133f0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
13400 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
13410 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
13420 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
13430 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
13440 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
13450 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
13460 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
13470 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
13480 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
13490 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
134a0 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
134b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
134c0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
134d0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
134e0 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
134f0 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
13500 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
13510 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
13520 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
13530 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
13540 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
13550 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
13560 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
13570 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
13580 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
13590 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
135a0 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
135b0 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
135c0 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
135d0 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
135e0 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
135f0 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
13600 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
13610 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
13620 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
13630 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
13640 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
13650 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
13660 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
13670 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
13680 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
13690 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
136a0 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
136b0 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
136c0 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
136d0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
136e0 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
136f0 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
13700 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
13710 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
13720 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
13730 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
13740 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
13750 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
13760 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
13770 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
13780 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
13790 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
137a0 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
137b0 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
137c0 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
137d0 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
137e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
137f0 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
13800 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
13810 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13820 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
13830 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
13840 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
13850 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
13860 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
13870 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
13880 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
13890 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
138a0 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
138b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
138c0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
138d0 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
138e0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
138f0 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
13900 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
13910 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
13920 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
13930 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
13940 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
13950 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
13960 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
13970 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
13980 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
13990 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
139a0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
139b0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
139c0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
139d0 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
139e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
139f0 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
13a00 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
13a10 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
13a20 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
13a30 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
13a40 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
13a50 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
13a60 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
13a70 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
13a80 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
13a90 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
13aa0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
13ab0 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
13ac0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
13ad0 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
13ae0 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
13af0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
13b00 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
13b10 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
13b20 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
13b30 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
13b40 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
13b50 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
13b60 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
13b70 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
13b80 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
13b90 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
13ba0 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
13bb0 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
13bc0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
13bd0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
13be0 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
13bf0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
13c00 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
13c10 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
13c20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
13c30 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
13c40 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
13c50 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
13c60 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
13c70 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
13c80 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
13c90 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
13ca0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13cb0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
13cc0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
13cd0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13ce0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
13cf0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
13d00 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
13d10 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
13d20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
13d30 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
13d40 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
13d50 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
13d60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13d70 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
13d80 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
13d90 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
13da0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
13db0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
13dc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13dd0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
13de0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
13df0 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
13e00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13e10 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
13e20 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
13e30 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
13e40 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
13e50 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
13e60 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
13e70 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
13e80 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
13e90 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13ea0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
13eb0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13ec0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
13ed0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
13ee0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
13ef0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
13f00 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
13f10 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
13f20 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13f30 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
13f40 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
13f50 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
13f60 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
13f70 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
13f80 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
13f90 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
13fa0 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
13fb0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
13fc0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13fd0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13fe0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13ff0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14000 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14010 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14020 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
14030 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
14040 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
14050 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
14060 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
14070 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
14080 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
14090 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
140a0 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
140b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
140c0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
140d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
140e0 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
140f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14100 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
14110 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14120 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
14130 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
14140 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
14150 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
14160 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
14170 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
14180 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
14190 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
141a0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
141b0 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
141c0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
141d0 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
141e0 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
141f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
14200 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
14210 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
14220 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
14230 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
14240 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
14250 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
14260 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14270 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
14280 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
14290 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
142a0 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
142b0 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
142c0 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
142d0 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
142e0 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
142f0 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
14300 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
14310 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
14320 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
14330 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14340 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
14350 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
14360 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14370 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14380 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14390 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
143a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
143b0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
143c0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
143d0 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
143e0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
143f0 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
14400 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14410 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
14420 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
14430 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
14440 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
14450 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
14460 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14470 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
14480 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14490 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
144a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
144b0 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
144c0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
144d0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
144e0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
144f0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
14500 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
14510 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
14520 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
14530 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
14540 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
14550 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
14560 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
14570 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
14580 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14590 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
145a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
145b0 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
145c0 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
145d0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
145e0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
145f0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
14600 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14610 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
14620 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
14630 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
14640 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
14650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
14660 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
14670 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
14680 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
14690 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
146a0 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
146b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
146c0 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
146d0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
146e0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
146f0 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
14700 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
14710 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
14720 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14730 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14740 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14750 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14760 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14770 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
14780 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
14790 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
147a0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
147b0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
147c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
147d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
147e0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
147f0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
14800 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14810 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
14820 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
14830 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14840 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14850 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
14860 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
14870 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14880 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
14890 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
148a0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
148b0 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
148c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
148d0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
148e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
148f0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14900 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
14910 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
14920 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
14930 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
14940 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
14950 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
14960 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
14970 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14980 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
14990 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
149a0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
149b0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
149c0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
149d0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
149e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
149f0 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
14a00 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
14a10 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
14a20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
14a30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14a40 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
14a50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14a60 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
14a70 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14a90 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
14aa0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14ab0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
14ac0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14ad0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14ae0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14af0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14b00 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  e..** The [sqlit
14b10 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
14b20 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
14b30 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
14b40 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
14b50 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
14b60 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
14b70 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
14b80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
14b90 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
14ba0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
14bb0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
14bc0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
14bd0 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
14be0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14bf0 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
14c00 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
14c10 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
14c20 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
14c30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14c40 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  MALL_MALLOC]] <d
14c50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14c60 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  SMALL_MALLOC</dt
14c70 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
14c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14c90 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  LL_MALLOC option
14ca0 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
14cb0 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70  gument of.** typ
14cc0 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
14cd0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
14ce0 20 77 68 69 63 68 20 69 66 20 74 72 75 65 20 70   which if true p
14cf0 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20 74  rovides a hint t
14d00 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74  o.** SQLite that
14d10 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64   it should avoid
14d20 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c   large memory al
14d30 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73  locations if pos
14d40 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65  sible..** SQLite
14d50 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72   will run faster
14d60 20 69 66 20 69 74 20 69 73 20 66 72 65 65 20 74   if it is free t
14d70 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d  o make large mem
14d80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c  ory allocations,
14d90 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70  .** but some app
14da0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70  lication might p
14db0 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f  refer to run slo
14dc0 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20  wer in exchange 
14dd0 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  for.** guarantee
14de0 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66  s about memory f
14df0 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  ragmentation tha
14e00 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69  t are possible i
14e10 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63  f large.** alloc
14e20 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64  ations are avoid
14e30 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  ed.  This hint i
14e40 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a  s normally off..
14e50 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14e60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14e70 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
14e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
14e90 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
14ea0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
14eb0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
14ec0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
14ed0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
14ee0 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e   type int,.** in
14ef0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
14f00 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
14f10 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
14f20 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
14f30 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c   of.** memory al
14f40 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
14f50 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
14f60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
14f70 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20  atistics are.** 
14f80 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
14f90 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
14fa0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
14fb0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
14fc0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
14fd0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
14fe0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
14ff0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
15000 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
15010 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
15020 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
15030 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
15040 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
15050 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20  status64()].**  
15060 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
15070 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
15080 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
15090 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
150a0 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
150b0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
150c0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
150d0 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
150e0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
150f0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
15100 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
15110 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
15120 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
15130 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15140 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
15150 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15160 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
15170 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
15180 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
15190 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f   option is no lo
151a0 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f  nger used..** </
151b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
151c0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
151d0 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
151e0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
151f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
15200 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15210 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
15220 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d  on specifies a m
15230 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68  emory pool.** th
15240 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
15250 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
15260 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
15270 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
15280 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
15290 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
152a0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
152b0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61  tion option is a
152c0 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70   no-op if an app
152d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
152e0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
152f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
15300 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
15310 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15320 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68  PCACHE2]..** ^Th
15330 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
15340 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
15350 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
15360 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
15370 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
15380 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29  ed memory (pMem)
15390 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
153a0 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69  ch page cache li
153b0 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  ne (sz),.** and 
153c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
153d0 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a  che lines (N)..*
153e0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
153f0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
15400 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
15410 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
15420 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
15430 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
15440 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
15450 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
15460 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
15470 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
15480 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
15490 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
154a0 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
154b0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
154c0 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c  mined using [SQL
154d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
154e0 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74  E_HDRSZ]..** ^It
154f0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
15500 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
15510 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
15520 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
15530 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
15540 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
15550 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72    The pMem.** ar
15560 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65  gument must be e
15570 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
15580 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65  nter or a pointe
15590 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  r to an 8-byte.*
155a0 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  * aligned block 
155b0 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  of memory of at 
155c0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
155d0 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73  , otherwise.** s
155e0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
155f0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
15600 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69  .** ^When pMem i
15610 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
15620 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74  te will strive t
15630 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  o use the memory
15640 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20   provided.** to 
15650 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63  satisfy page cac
15660 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e  he needs, fallin
15670 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74  g back to [sqlit
15680 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a  e3_malloc()] if.
15690 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20  ** a page cache 
156a0 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74  line is larger t
156b0 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20  han sz bytes or 
156c0 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d  if all of the pM
156d0 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  em buffer.** is 
156e0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49  exhausted..** ^I
156f0 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61  f pMem is NULL a
15700 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  nd N is non-zero
15710 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61  , then each data
15720 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15730 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69  ** does an initi
15740 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69  al bulk allocati
15750 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  on for page cach
15760 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d  e memory.** from
15770 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15780 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66  ()] sufficient f
15790 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73  or N cache lines
157a0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
157b0 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34  e or.** of -1024
157c0 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73  *N bytes if N is
157d0 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66   negative, . ^If
157e0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
157f0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
15800 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
15810 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
15820 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61  ed by the initia
15830 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  l.** allocation,
15840 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
15850 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
15860 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65  lloc()] separate
15870 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61  ly for each.** a
15880 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20  dditional cache 
15890 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  line. </dd>.**.*
158a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
158b0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
158c0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
158d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
158e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
158f0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
15900 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
15910 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
15920 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
15930 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
15940 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
15950 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
15960 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
15970 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
15980 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
15990 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
159a0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
159b0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
159c0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
159d0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
159e0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
159f0 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
15a00 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
15a10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
15a20 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
15a30 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
15a40 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
15a50 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
15a60 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
15a70 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
15a80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
15a90 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
15aa0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
15ab0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
15ac0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
15ad0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
15ae0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
15af0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
15b00 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
15b10 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
15b20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
15b30 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
15b40 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
15b50 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
15b60 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
15b70 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
15b80 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
15b90 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
15ba0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
15bb0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
15bc0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
15bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
15be0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
15bf0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
15c00 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
15c10 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
15c20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
15c30 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
15c40 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
15c50 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
15c60 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
15c70 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
15c80 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
15c90 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
15ca0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
15cb0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
15cc0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
15cd0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
15ce0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
15cf0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
15d00 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
15d10 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
15d20 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
15d30 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
15d40 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
15d50 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
15d60 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
15d70 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
15d80 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15d90 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
15da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
15db0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
15dc0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15dd0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
15de0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15df0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15e00 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
15e10 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
15e20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15e30 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15e40 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
15e50 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
15e60 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
15e70 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
15e80 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
15e90 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
15ea0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
15eb0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
15ec0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
15ed0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
15ee0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
15ef0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15f00 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15f10 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
15f20 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
15f30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
15f40 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
15f50 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15f60 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
15f70 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
15f80 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15f90 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
15fa0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
15fb0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
15fc0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
15fd0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
15fe0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
15ff0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
16000 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
16010 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
16020 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
16030 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16040 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
16050 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
16060 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
16070 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16080 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
16090 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
160a0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
160b0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
160c0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
160d0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
160e0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
160f0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
16100 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
16110 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
16120 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
16130 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
16140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
16150 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
16160 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
16170 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
16180 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
16190 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
161a0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
161b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
161c0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
161d0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
161e0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
161f0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
16200 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
16210 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
16220 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
16230 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
16240 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
16250 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
16260 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
16270 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
16280 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
16290 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
162a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
162b0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
162c0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
162d0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
162e0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
162f0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
16300 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
16310 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
16320 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
16330 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
16340 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16350 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
16360 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
16370 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16380 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16390 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
163a0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
163b0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
163c0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
163d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
163e0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
163f0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
16400 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
16410 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
16420 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
16430 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
16440 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
16450 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16460 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
16470 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
16480 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
16490 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
164a0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
164b0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
164c0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
164d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
164e0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
164f0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
16500 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
16510 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
16520 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
16530 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16540 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
16550 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
16560 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
16570 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
16580 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
16590 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
165a0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
165b0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
165c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
165d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
165e0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
165f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
16600 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16610 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16620 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
16630 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
16640 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
16650 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
16660 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
16670 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16680 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
16690 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
166a0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
166b0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
166c0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
166d0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
166e0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
166f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
16700 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
16710 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
16720 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16730 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
16740 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16750 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
16760 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
16770 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16780 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
16790 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
167a0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
167b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
167c0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
167d0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
167e0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
167f0 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
16800 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
16810 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
16820 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
16830 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
16840 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16850 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
16860 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
16870 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
16880 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
16890 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
168a0 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
168b0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
168c0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
168d0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
168e0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
168f0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
16900 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
16910 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
16920 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
16930 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
16940 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
16950 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
16960 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
16970 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
16980 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
16990 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
169a0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
169b0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
169c0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
169d0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
169e0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
169f0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
16a00 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
16a10 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
16a20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
16a30 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
16a40 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
16a50 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
16a60 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
16a70 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
16a80 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
16a90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16aa0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
16ab0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
16ac0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
16ad0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
16ae0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
16af0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
16b00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
16b10 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
16b20 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
16b30 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
16b40 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
16b50 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
16b60 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
16b70 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
16b80 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
16b90 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
16ba0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
16bb0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
16bc0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16bd0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
16be0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
16bf0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
16c00 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
16c10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
16c20 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
16c30 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
16c40 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
16c50 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
16c60 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
16c70 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
16c80 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
16c90 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
16ca0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
16cb0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
16cc0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
16cd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16ce0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
16cf0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
16d00 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
16d10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
16d30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16d40 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
16d50 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
16d60 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
16d70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
16d80 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
16d90 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
16da0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
16db0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
16dc0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
16dd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
16de0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
16df0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16e00 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
16e10 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
16e20 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
16e30 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
16e40 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
16e50 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
16e60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
16e70 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
16e80 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
16e90 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
16ea0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
16eb0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
16ec0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
16ed0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
16ee0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
16ef0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
16f00 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
16f10 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
16f20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
16f30 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
16f40 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
16f50 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
16f60 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
16f70 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
16f80 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
16f90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
16fa0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
16fb0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
16fc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
16fd0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
16fe0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
16ff0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
17000 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
17010 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
17020 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
17030 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
17040 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
17050 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
17060 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
17070 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
17080 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
17090 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
170a0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
170b0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
170c0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
170d0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
170e0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
170f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
17100 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
17110 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
17120 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
17130 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
17140 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17150 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
17160 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
17170 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
17180 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
17190 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
171a0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
171b0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
171c0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
171d0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
171e0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
171f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17200 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
17210 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
17220 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
17230 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
17240 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
17250 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
17260 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
17270 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
17280 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
17290 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
172a0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
172b0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
172c0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
172d0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
172e0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
172f0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
17300 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
17310 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
17320 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
17330 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
17340 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
17350 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
17360 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
17370 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
17380 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
17390 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
173a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
173b0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
173c0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
173d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
173e0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
173f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17400 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
17410 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
17420 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
17430 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
17440 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
17450 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
17460 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
17470 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
17480 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
17490 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
174a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
174b0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
174c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
174d0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
174e0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
174f0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
17500 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
17510 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
17520 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
17530 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
17540 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
17550 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
17560 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
17570 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
17580 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
17590 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
175a0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
175b0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
175c0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
175d0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
175e0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
175f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
17600 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
17610 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
17620 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
17630 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
17640 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
17650 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
17660 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
17670 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
17680 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
17690 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
176a0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
176b0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
176c0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
176d0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
176e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
176f0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
17700 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
17710 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
17720 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
17730 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
17740 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
17750 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
17760 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
17770 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
17780 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
17790 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
177a0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
177b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
177c0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
177d0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
177e0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
177f0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
17800 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
17810 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
17820 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
17830 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
17840 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
17850 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
17860 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
17870 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
17880 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
17890 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
178a0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
178b0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
178c0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
178d0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
178e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
178f0 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
17900 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17910 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
17920 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
17930 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
17940 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
17950 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
17960 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
17970 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
17980 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
17990 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
179a0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
179b0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
179c0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
179d0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
179e0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
179f0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
17a00 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
17a10 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
17a20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17a30 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
17a40 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
17a50 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
17a60 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
17a70 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
17a80 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
17a90 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
17aa0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
17ab0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
17ac0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
17ad0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
17ae0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
17af0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
17b00 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
17b10 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
17b20 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
17b30 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
17b40 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
17b50 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17b60 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
17b70 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
17b80 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
17b90 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
17ba0 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
17bb0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
17bc0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
17bd0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
17be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17bf0 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
17c00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17c10 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17c20 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
17c30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
17c40 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
17c50 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
17c60 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
17c70 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
17c80 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
17c90 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
17ca0 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
17cb0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
17cc0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
17cd0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17ce0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
17cf0 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
17d00 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
17d10 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
17d20 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
17d30 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
17d40 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
17d50 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17d60 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
17d70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
17d80 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
17d90 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17da0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
17db0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
17dc0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
17dd0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
17de0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
17df0 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
17e00 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
17e10 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
17e20 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
17e30 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
17e40 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
17e50 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
17e60 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
17e70 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
17e80 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
17e90 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
17ea0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
17eb0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
17ec0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
17ed0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
17ee0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
17ef0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
17f00 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17f10 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
17f20 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17f30 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
17f40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17f50 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
17f60 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
17f70 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
17f80 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
17f90 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
17fa0 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
17fb0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
17fc0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
17fd0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
17fe0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
17ff0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
18000 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
18010 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
18020 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
18030 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
18040 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
18050 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
18060 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
18070 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
18080 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
18090 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
180a0 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
180b0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
180c0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
180d0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
180e0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
180f0 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
18100 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
18110 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
18120 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
18130 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  value..**.** [[S
18140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
18150 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a  TJRNL_SPILL]].**
18160 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
18170 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
18180 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  L.** <dd>^The SQ
18190 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
181a0 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f  JRNL_SPILL optio
181b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
181c0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
181d0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20  .** becomes the 
181e0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [statement journ
181f0 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73  al] spill-to-dis
18200 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a  k threshold.  .*
18210 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75  * [Statement jou
18220 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20  rnals] are held 
18230 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20  in memory until 
18240 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62  their size (in b
18250 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73  ytes).** exceeds
18260 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c   this threshold,
18270 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20   at which point 
18280 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e  they are written
18290 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20   to disk..** Or 
182a0 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64  if the threshold
182b0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e   is -1, statemen
182c0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61  t journals are a
182d0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78  lways held.** ex
182e0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d  clusively in mem
182f0 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61  ory..** Since ma
18300 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  ny statement jou
18310 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f  rnals never beco
18320 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e  me large, settin
18330 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74  g the spill.** t
18340 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61  hreshold to a va
18350 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69  lue such as 64Ki
18360 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65  B can greatly re
18370 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20  duce the amount 
18380 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72  of.** I/O requir
18390 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74  ed to support st
183a0 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b  atement rollback
183b0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
183c0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
183d0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72  setting is contr
183e0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  olled by the.** 
183f0 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c  [SQLITE_STMTJRNL
18400 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d  _SPILL] compile-
18410 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a  time option..**.
18420 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
18430 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a  IG_SORTERREF_SIZ
18440 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
18450 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52  E_CONFIG_SORTERR
18460 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54  EF_SIZE.** <dd>T
18470 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
18480 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20  _SORTERREF_SIZE 
18490 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61  option accepts a
184a0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
184b0 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e  r.** of type (in
184c0 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c  t) - the new val
184d0 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72  ue of the sorter
184e0 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20  -reference size 
184f0 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73  threshold..** Us
18500 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69  ually, when SQLi
18510 74 65 20 75 73 65 73 20 61 6e 20 65 78 74 65 72  te uses an exter
18520 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65  nal sort to orde
18530 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64  r records accord
18540 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44  ing.** to an ORD
18550 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c  ER BY clause, al
18560 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69 72 65  l fields require
18570 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20  d by the caller 
18580 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74  are present in t
18590 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63  he.** sorted rec
185a0 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69  ords. However, i
185b0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
185c0 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65  nes based on the
185d0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a   declared type.*
185e0 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c  * of a table col
185f0 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c  umn that its val
18600 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74  ues are likely t
18610 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67 65 20  o be very large 
18620 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e  - larger.** than
18630 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20   the configured 
18640 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65  sorter-reference
18650 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20   size threshold 
18660 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e  - then a referen
18670 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20  ce.** is stored 
18680 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20 72  in each sorted r
18690 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65  ecord and the re
186a0 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61  quired column va
186b0 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66  lues loaded.** f
186c0 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65  rom the database
186d0 20 61 73 20 72 65 63 6f 72 64 73 20 61 72 65 20   as records are 
186e0 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74  returned in sort
186f0 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65  ed order. The de
18700 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66  fault.** value f
18710 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  or this option i
18720 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74  s to never use t
18730 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  his optimization
18740 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a  . Specifying a .
18750 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ** negative valu
18760 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f  e for this optio
18770 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65 20 64  n restores the d
18780 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72  efault behaviour
18790 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ..** This option
187a0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
187b0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
187c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
187d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
187e0 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52  BLE_SORTER_REFER
187f0 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74  ENCES] compile-t
18800 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ime option..**.*
18810 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
18820 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 5d  G_MEMDB_MAXSIZE]
18830 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
18840 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58  CONFIG_MEMDB_MAX
18850 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  SIZE.** <dd>The 
18860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
18870 4d 44 42 5f 4d 41 58 53 49 5a 45 20 6f 70 74 69  MDB_MAXSIZE opti
18880 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73 69 6e  on accepts a sin
18890 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  gle parameter.**
188a0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d   [sqlite3_int64]
188b0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
188c0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
188d0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 66 6f 72  maximum size for
188e0 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a   an in-memory.**
188f0 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
18900 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
18910 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29 5d 2e  _deserialize()].
18920 20 20 54 68 69 73 20 64 65 66 61 75 6c 74 20 6d    This default m
18930 61 78 69 6d 75 6d 0a 2a 2a 20 73 69 7a 65 20 63  aximum.** size c
18940 61 6e 20 62 65 20 61 64 6a 75 73 74 65 64 20 75  an be adjusted u
18950 70 20 6f 72 20 64 6f 77 6e 20 66 6f 72 20 69 6e  p or down for in
18960 64 69 76 69 64 75 61 6c 20 64 61 74 61 62 61 73  dividual databas
18970 65 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  es using the.** 
18980 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
18990 5a 45 5f 4c 49 4d 49 54 5d 20 5b 73 71 6c 69 74  ZE_LIMIT] [sqlit
189a0 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 7c  e3_file_control|
189b0 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 5d 2e 20 20  file-control].  
189c0 49 66 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  If this.** confi
189d0 67 75 72 61 74 69 6f 6e 20 73 65 74 74 69 6e 67  guration setting
189e0 20 69 73 20 6e 65 76 65 72 20 75 73 65 64 2c 20   is never used, 
189f0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
18a00 20 6d 61 78 69 6d 75 6d 20 69 73 20 64 65 74 65   maximum is dete
18a10 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
18a20 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 42 5f 44   [SQLITE_MEMDB_D
18a30 45 46 41 55 4c 54 5f 4d 41 58 53 49 5a 45 5d 20  EFAULT_MAXSIZE] 
18a40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
18a50 69 6f 6e 2e 20 20 49 66 20 74 68 61 74 0a 2a 2a  ion.  If that.**
18a60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
18a70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 73 65 74 2c  tion is not set,
18a80 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
18a90 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 31 30 37  t maximum is 107
18aa0 33 37 34 31 38 32 34 2e 0a 2a 2a 20 3c 2f 64 6c  3741824..** </dl
18ab0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
18ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
18ad0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
18ae0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
18af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
18b00 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
18b10 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
18b20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
18b30 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
18b40 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
18b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
18b60 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
18b70 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
18b80 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
18b90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18ba0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
18bb0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
18bc0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18bd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18be0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
18bf0 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  6  /* No longer 
18c00 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
18c10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
18c20 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
18c30 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
18c40 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
18c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18c60 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
18c70 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
18c80 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
18c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ca0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
18cb0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
18cc0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
18cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
18ce0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
18cf0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
18d00 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
18d10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18d20 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
18d30 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
18d40 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
18d50 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
18d60 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
18d70 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
18d80 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
18d90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18da0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
18db0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int 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 50 43 41 43  LITE_CONFIG_PCAC
18de0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
18df0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
18e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
18e10 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
18e20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
18e30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18e40 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
18e50 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
18e60 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
18e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
18e80 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
18e90 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18ea0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18eb0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
18ec0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
18ed0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
18ee0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18ef0 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
18f00 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
18f10 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
18f20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18f30 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
18f40 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
18f50 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
18f60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18f70 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
18f80 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
18f90 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
18fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
18fb0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
18fc0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
18fd0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
18fe0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ff0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
19000 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
19010 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
19020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19030 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
19040 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
19050 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
19060 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19070 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
19080 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
19090 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
190a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
190b0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
190c0 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
190d0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
190e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
190f0 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
19100 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20 2f  LOC        27  /
19110 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
19120 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19130 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a  IG_SORTERREF_SIZ
19140 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20 69 6e  E      28  /* in
19150 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
19160 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
19170 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20 20  _MEMDB_MAXSIZE  
19180 20 20 20 20 20 32 39 20 20 2f 2a 20 73 71 6c 69       29  /* sqli
19190 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f 2a  te3_int64 */../*
191a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
191b0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
191c0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
191d0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
191e0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
191f0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
19200 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
19210 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
19220 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
19230 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
19240 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
19250 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
19260 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
19270 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
19280 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
19290 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
192a0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
192b0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
192c0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
192d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
192e0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
192f0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
19300 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
19310 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
19320 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
19330 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
19340 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
19350 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
19360 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
19370 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
19380 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
19390 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
193a0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
193b0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
193c0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
193d0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
193e0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
193f0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
19400 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  l>.** [[SQLITE_D
19410 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
19420 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
19430 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
19440 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
19450 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
19460 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
19470 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
19480 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
19490 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
194a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
194b0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
194c0 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
194d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
194e0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
194f0 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
19500 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
19510 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
19520 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
19530 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
19540 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
19550 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
19560 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
19570 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
19580 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
19590 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
195a0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
195b0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
195c0 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
195d0 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
195e0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
195f0 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
19600 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
19610 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
19620 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
19630 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
19640 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
19650 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
19660 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
19670 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
19680 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
19690 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
196a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
196b0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
196c0 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
196d0 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
196e0 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
196f0 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
19700 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
19710 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
19720 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
19730 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
19740 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
19750 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
19760 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
19770 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
19780 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
19790 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
197a0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
197b0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
197c0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
197d0 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
197e0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
197f0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
19800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19810 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
19820 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
19830 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
19840 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
19850 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
19860 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
19870 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
19880 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
19890 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
198a0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
198b0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
198c0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
198d0 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
198e0 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
198f0 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
19900 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
19910 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
19920 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
19930 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
19940 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
19950 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
19960 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
19970 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
19980 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
19990 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46   [[SQLITE_DBCONF
199a0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 5d 5d  IG_ENABLE_FKEY]]
199b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
199c0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
199d0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
199e0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
199f0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
19a00 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
19a10 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
19a20 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
19a30 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
19a40 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
19a50 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
19a60 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
19a70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
19a80 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
19a90 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
19aa0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
19ab0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
19ac0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
19ad0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
19ae0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
19af0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
19b00 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
19b10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19b20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19b30 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
19b40 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
19b50 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
19b60 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
19b70 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
19b80 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
19b90 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
19ba0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
19bb0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
19bc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
19bd0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
19be0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
19bf0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
19c00 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
19c10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
19c20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19c30 41 42 4c 45 5f 54 52 49 47 47 45 52 5d 5d 0a 2a  ABLE_TRIGGER]].*
19c40 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19c50 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
19c60 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
19c70 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
19c80 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
19c90 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
19ca0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
19cb0 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
19cc0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
19cd0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19ce0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
19cf0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
19d00 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
19d10 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19d20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
19d30 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
19d40 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
19d50 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
19d60 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
19d70 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
19d80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
19d90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
19da0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
19db0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
19dc0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
19dd0 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
19de0 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
19df0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
19e00 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
19e10 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
19e20 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
19e30 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
19e40 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
19e50 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
19e60 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19e70 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
19e80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
19e90 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19ea0 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
19eb0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
19ec0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19ed0 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c  _FTS3_TOKENIZER<
19ee0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
19ef0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
19f00 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
19f10 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 5b 66  isable the.** [f
19f20 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d  ts3_tokenizer()]
19f30 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20   function which 
19f40 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  is part of the.*
19f50 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65  * [FTS3] full-te
19f60 78 74 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65  xt search engine
19f70 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54   extension..** T
19f80 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
19f90 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
19fa0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
19fb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19fc0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19fd0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19fe0 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  le fts3_tokenize
19ff0 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69  r() or.** positi
1a000 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 74 73  ve to enable fts
1a010 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72  3_tokenizer() or
1a020 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
1a030 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  ve the setting.*
1a040 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  * unchanged..** 
1a050 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1a060 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
1a070 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
1a080 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
1a090 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
1a0a0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
1a0b0 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  her fts3_tokeniz
1a0c0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  er is disabled o
1a0d0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
1a0e0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
1a0f0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
1a100 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
1a110 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
1a120 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
1a130 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20  the new setting 
1a140 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
1a150 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
1a160 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1a170 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f  FIG_ENABLE_LOAD_
1a180 45 58 54 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a 20 3c  EXTENSION]].** <
1a190 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1a1a0 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
1a1b0 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a  XTENSION</dt>.**
1a1c0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
1a1d0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
1a1e0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
1a1f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
1a200 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
1a210 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65  * interface inde
1a220 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65  pendently of the
1a230 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
1a240 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
1a250 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
1a260 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
1a270 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65  tension()] API e
1a280 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
1a290 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43  es both the.** C
1a2a0 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  -API [sqlite3_lo
1a2b0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
1a2c0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
1a2d0 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e  tion [load_exten
1a2e0 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72  sion()]..** Ther
1a2f0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
1a300 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
1a310 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  ents..** When th
1a320 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a330 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
1a340 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e  ce is 1, then on
1a350 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a  ly the C-API is.
1a360 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74  ** enabled and t
1a370 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
1a380 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64  remains disabled
1a390 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
1a3a0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1a3b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1a3c0 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68   0, then both th
1a3d0 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20  e C-API and the 
1a3e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  SQL function are
1a3f0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66   disabled..** If
1a400 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1a410 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ent is -1, then 
1a420 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d  no changes are m
1a430 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20  ade to state of 
1a440 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d  either the.** C-
1a450 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66  API or the SQL f
1a460 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
1a470 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a480 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1a490 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
1a4a0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
1a4b0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
1a4c0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
1a4d0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
1a4e0 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
1a4f0 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62  face.** is disab
1a500 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66  led or enabled f
1a510 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
1a520 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
1a530 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a  parameter may.**
1a540 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
1a550 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  er, in which cas
1a560 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
1a570 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
1a580 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e  d back..** </dd>
1a590 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
1a5a0 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e  DBCONFIG_MAINDBN
1a5b0 41 4d 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  AME]] <dt>SQLITE
1a5c0 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
1a5d0 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NAME</dt>.** <dd
1a5e0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
1a5f0 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  s used to change
1a600 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1a610 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65   "main" database
1a620 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68  .** schema.  ^Th
1a630 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20  e sole argument 
1a640 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1a650 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20  a constant UTF8 
1a660 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20  string.** which 
1a670 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
1a680 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  new schema name 
1a690 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69  in place of "mai
1a6a0 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  n".  ^SQLite.** 
1a6b0 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20  does not make a 
1a6c0 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20  copy of the new 
1a6d0 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65  main schema name
1a6e0 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20   string, so the 
1a6f0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
1a700 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
1a710 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73  the argument pas
1a720 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42  sed into this DB
1a730 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73  CONFIG option is
1a740 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e   unchanged.** un
1a750 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61  til after the da
1a760 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a770 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64  n closes..** </d
1a780 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
1a790 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b  E_DBCONFIG_NO_CK
1a7a0 50 54 5f 4f 4e 5f 43 4c 4f 53 45 5d 5d 20 0a 2a  PT_ON_CLOSE]] .*
1a7b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
1a7c0 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
1a7d0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
1a7e0 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65  dd> Usually, whe
1a7f0 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20  n a database in 
1a800 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73  wal mode is clos
1a810 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66  ed or detached f
1a820 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61  rom a .** databa
1a830 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74  se handle, SQLit
1a840 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73  e checks if this
1a850 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20   will mean that 
1a860 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f  there are now no
1a870 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   .** connections
1a880 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64   at all to the d
1a890 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20  atabase. If so, 
1a8a0 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68  it performs a ch
1a8b0 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65  eckpoint .** ope
1a8c0 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c  ration before cl
1a8d0 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63  osing the connec
1a8e0 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f  tion. This optio
1a8f0 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  n may be used to
1a900 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69  .** override thi
1a910 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65  s behaviour. The
1a920 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1a930 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
1a940 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  operation.** is 
1a950 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f 73  an integer - pos
1a960 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c 65  itive to disable
1a970 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
1a980 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28  close, or zero (
1a990 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20  the.** default) 
1a9a0 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20  to enable them, 
1a9b0 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f 20  and negative to 
1a9c0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
1a9d0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
1a9e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1a9f0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
1aa00 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  r to an integer.
1aa10 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  ** into which is
1aa20 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
1aa30 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
1aa40 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  her checkpoints-
1aa50 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65  on-close.** have
1aa60 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
1aa70 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e   0 if they are n
1aa80 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
1aa90 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c  f they are..** <
1aaa0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
1aab0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1aac0 42 4c 45 5f 51 50 53 47 5d 5d 20 3c 64 74 3e 53  BLE_QPSG]] <dt>S
1aad0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1aae0 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a  NABLE_QPSG</dt>.
1aaf0 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
1ab00 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1ab10 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20  BLE_QPSG option 
1ab20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61  activates or dea
1ab30 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20  ctivates.** the 
1ab40 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73  [query planner s
1ab50 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74  tability guarant
1ab60 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65  ee] (QPSG).  Whe
1ab70 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63  n the QPSG is ac
1ab80 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c  tive,.** a singl
1ab90 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74  e SQL query stat
1aba0 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79  ement will alway
1abb0 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61  s use the same a
1abc0 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c  lgorithm regardl
1abd0 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73  ess.** of values
1abe0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
1abf0 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50  eters].)^ The QP
1ac00 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65  SG disables some
1ac10 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74   query optimizat
1ac20 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f  ions.** that loo
1ac30 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20  k at the values 
1ac40 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  of bound paramet
1ac50 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d  ers, which can m
1ac60 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73  ake some queries
1ac70 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74  .** slower.  But
1ac80 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68   the QPSG has th
1ac90 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d  e advantage of m
1aca0 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20  ore predictable 
1acb0 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a  behavior.  With.
1acc0 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69  ** the QPSG acti
1acd0 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ve, SQLite will 
1ace0 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73  always use the s
1acf0 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69  ame query plan i
1ad00 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a  n the field as.*
1ad10 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e  * was used durin
1ad20 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65  g testing in the
1ad30 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72   lab..** The fir
1ad40 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1ad50 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 61  his setting is a
1ad60 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
1ad70 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
1ad80 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70 6f  .** the QPSG, po
1ad90 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
1ada0 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69   QPSG, or negati
1adb0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
1adc0 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
1add0 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64  nged. The second
1ade0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1adf0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
1ae00 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
1ae10 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
1ae20 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
1ae30 65 20 77 68 65 74 68 65 72 20 74 68 65 20 51 50  e whether the QP
1ae40 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  SG is disabled o
1ae50 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
1ae60 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
1ae70 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
1ae80 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46   [[SQLITE_DBCONF
1ae90 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 5d 5d  IG_TRIGGER_EQP]]
1aea0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
1aeb0 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
1aec0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79  </dt>.** <dd> By
1aed0 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75   default, the ou
1aee0 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20  tput of EXPLAIN 
1aef0 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61  QUERY PLAN comma
1af00 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a  nds does not .**
1af10 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20   include output 
1af20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f  for any operatio
1af30 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ns performed by 
1af40 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1af50 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e  . This.** option
1af60 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
1af70 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64 65  or clear (the de
1af80 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68  fault) a flag th
1af90 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a  at governs this.
1afa0 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65  ** behavior. The
1afb0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1afc0 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
1afd0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
1afe0 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73  integer -.** pos
1aff0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
1b000 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67 67  output for trigg
1b010 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20  er programs, or 
1b020 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20  zero to disable 
1b030 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69  it,.** or negati
1b040 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
1b050 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
1b060 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
1b070 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1b080 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
1b090 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
1b0a0 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20   is written .** 
1b0b0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
1b0c0 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75  te whether outpu
1b0d0 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68  t-for-triggers h
1b0e0 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  as been disabled
1b0f0 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69   - 0 if .** it i
1b100 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20  s not disabled, 
1b110 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a  1 if it is.  .**
1b120 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
1b130 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52  QLITE_DBCONFIG_R
1b140 45 53 45 54 5f 44 41 54 41 42 41 53 45 5d 5d 20  ESET_DATABASE]] 
1b150 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1b160 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41  FIG_RESET_DATABA
1b170 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  SE</dt>.** <dd> 
1b180 53 65 74 20 74 68 65 20 53 51 4c 49 54 45 5f 44  Set the SQLITE_D
1b190 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41  BCONFIG_RESET_DA
1b1a0 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e 64 20  TABASE flag and 
1b1b0 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41 43  then run.** [VAC
1b1c0 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  UUM] in order to
1b1d0 20 72 65 73 65 74 20 61 20 64 61 74 61 62 61 73   reset a databas
1b1e0 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70  e back to an emp
1b1f0 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 77  ty database.** w
1b200 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20 61 6e  ith no schema an
1b210 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 54 68  d no content. Th
1b220 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 63  e following proc
1b230 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e 20 66  ess works even f
1b240 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20 63 6f  or.** a badly co
1b250 72 72 75 70 74 65 64 20 64 61 74 61 62 61 73 65  rrupted database
1b260 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   file:.** <ol>.*
1b270 2a 20 3c 6c 69 3e 20 49 66 20 74 68 65 20 64 61  * <li> If the da
1b280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b290 6e 20 69 73 20 6e 65 77 6c 79 20 6f 70 65 6e 65  n is newly opene
1b2a0 64 2c 20 6d 61 6b 65 20 73 75 72 65 20 69 74 20  d, make sure it 
1b2b0 68 61 73 20 72 65 61 64 20 74 68 65 0a 2a 2a 20  has read the.** 
1b2c0 20 20 20 20 20 64 61 74 61 62 61 73 65 20 73 63       database sc
1b2d0 68 65 6d 61 20 62 79 20 70 72 65 70 61 72 69 6e  hema by preparin
1b2e0 67 20 74 68 65 6e 20 64 69 73 63 61 72 64 69 6e  g then discardin
1b2f0 67 20 73 6f 6d 65 20 71 75 65 72 79 20 61 67 61  g some query aga
1b300 69 6e 73 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  inst the.**     
1b310 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20 63 61   database, or ca
1b320 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 74 61  lling sqlite3_ta
1b330 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64  ble_column_metad
1b340 61 74 61 28 29 2c 20 69 67 6e 6f 72 69 6e 67 20  ata(), ignoring 
1b350 61 6e 79 0a 2a 2a 20 20 20 20 20 20 65 72 72 6f  any.**      erro
1b360 72 73 2e 20 20 54 68 69 73 20 73 74 65 70 20 69  rs.  This step i
1b370 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61 72 79  s only necessary
1b380 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   if the applicat
1b390 69 6f 6e 20 64 65 73 69 72 65 73 20 74 6f 20 6b  ion desires to k
1b3a0 65 65 70 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  eep.**      the 
1b3b0 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20  database in WAL 
1b3c0 6d 6f 64 65 20 61 66 74 65 72 20 74 68 65 20 72  mode after the r
1b3d0 65 73 65 74 20 69 66 20 69 74 20 77 61 73 20 69  eset if it was i
1b3e0 6e 20 57 41 4c 20 6d 6f 64 65 20 62 65 66 6f 72  n WAL mode befor
1b3f0 65 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 72 65  e.**      the re
1b400 73 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69 3e 20 73  set.  .** <li> s
1b410 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
1b420 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42 43 4f  (db, SQLITE_DBCO
1b430 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42  NFIG_RESET_DATAB
1b440 41 53 45 2c 20 31 2c 20 30 29 3b 0a 2a 2a 20 3c  ASE, 1, 0);.** <
1b450 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  li> [sqlite3_exe
1b460 63 5d 28 64 62 2c 20 22 5b 56 41 43 55 55 4d 5d  c](db, "[VACUUM]
1b470 22 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  ", 0, 0, 0);.** 
1b480 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f  <li> sqlite3_db_
1b490 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54  config(db, SQLIT
1b4a0 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54  E_DBCONFIG_RESET
1b4b0 5f 44 41 54 41 42 41 53 45 2c 20 30 2c 20 30 29  _DATABASE, 0, 0)
1b4c0 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20 42 65  ;.** </ol>.** Be
1b4d0 63 61 75 73 65 20 72 65 73 65 74 74 69 6e 67 20  cause resetting 
1b4e0 61 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  a database is de
1b4f0 73 74 72 75 63 74 69 76 65 20 61 6e 64 20 69 72  structive and ir
1b500 72 65 76 65 72 73 69 62 6c 65 2c 20 74 68 65 0a  reversible, the.
1b510 2a 2a 20 70 72 6f 63 65 73 73 20 72 65 71 75 69  ** process requi
1b520 72 65 73 20 74 68 65 20 75 73 65 20 6f 66 20 74  res the use of t
1b530 68 69 73 20 6f 62 73 63 75 72 65 20 41 50 49 20  his obscure API 
1b540 61 6e 64 20 6d 75 6c 74 69 70 6c 65 20 73 74 65  and multiple ste
1b550 70 73 20 74 6f 20 68 65 6c 70 0a 2a 2a 20 65 6e  ps to help.** en
1b560 73 75 72 65 20 74 68 61 74 20 69 74 20 64 6f 65  sure that it doe
1b570 73 20 6e 6f 74 20 68 61 70 70 65 6e 20 62 79 20  s not happen by 
1b580 61 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  accident..**.** 
1b590 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
1b5a0 47 5f 44 45 46 45 4e 53 49 56 45 5d 5d 20 3c 64  G_DEFENSIVE]] <d
1b5b0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1b5c0 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f 64 74 3e  G_DEFENSIVE</dt>
1b5d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
1b5e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46 45  TE_DBCONFIG_DEFE
1b5f0 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20 61 63 74  NSIVE option act
1b600 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69  ivates or deacti
1b610 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22 64 65  vates the.** "de
1b620 66 65 6e 73 69 76 65 22 20 66 6c 61 67 20 66 6f  fensive" flag fo
1b630 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
1b640 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e 20 74  nection.  When t
1b650 68 65 20 64 65 66 65 6e 73 69 76 65 0a 2a 2a 20  he defensive.** 
1b660 66 6c 61 67 20 69 73 20 65 6e 61 62 6c 65 64 2c  flag is enabled,
1b670 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74 75 72   language featur
1b680 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 20 6f 72  es that allow or
1b690 64 69 6e 61 72 79 20 53 51 4c 20 74 6f 20 0a 2a  dinary SQL to .*
1b6a0 2a 20 64 65 6c 69 62 65 72 61 74 65 6c 79 20 63  * deliberately c
1b6b0 6f 72 72 75 70 74 20 74 68 65 20 64 61 74 61 62  orrupt the datab
1b6c0 61 73 65 20 66 69 6c 65 20 61 72 65 20 64 69 73  ase file are dis
1b6d0 61 62 6c 65 64 2e 20 20 54 68 65 20 64 69 73 61  abled.  The disa
1b6e0 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75 72 65 73  bled.** features
1b6f0 20 69 6e 63 6c 75 64 65 20 62 75 74 20 61 72 65   include but are
1b700 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74 6f 20   not limited to 
1b710 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a 2a  the following:.*
1b720 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
1b730 68 65 20 5b 50 52 41 47 4d 41 20 77 72 69 74 61  he [PRAGMA writa
1b740 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d 20 73  ble_schema=ON] s
1b750 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 6c 69  tatement..** <li
1b760 3e 20 54 68 65 20 5b 50 52 41 47 4d 41 20 6a 6f  > The [PRAGMA jo
1b770 75 72 6e 61 6c 5f 6d 6f 64 65 3d 4f 46 46 5d 20  urnal_mode=OFF] 
1b780 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 6c  statement..** <l
1b790 69 3e 20 57 72 69 74 65 73 20 74 6f 20 74 68 65  i> Writes to the
1b7a0 20 5b 73 71 6c 69 74 65 5f 64 62 70 61 67 65 5d   [sqlite_dbpage]
1b7b0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a   virtual table..
1b7c0 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63 74 20 77  ** <li> Direct w
1b7d0 72 69 74 65 73 20 74 6f 20 5b 73 68 61 64 6f 77  rites to [shadow
1b7e0 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 3c 2f 75   tables]..** </u
1b7f0 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  l>.** </dd>.**.*
1b800 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1b810 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 43 48  FIG_WRITABLE_SCH
1b820 45 4d 41 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EMA]] <dt>SQLITE
1b830 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 41 42  _DBCONFIG_WRITAB
1b840 4c 45 5f 53 43 48 45 4d 41 3c 2f 64 74 3e 0a 2a  LE_SCHEMA</dt>.*
1b850 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
1b860 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 41 42  _DBCONFIG_WRITAB
1b870 4c 45 5f 53 43 48 45 4d 41 20 6f 70 74 69 6f 6e  LE_SCHEMA option
1b880 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65   activates or de
1b890 61 63 74 69 76 61 74 65 73 20 74 68 65 0a 2a 2a  activates the.**
1b8a0 20 22 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d   "writable_schem
1b8b0 61 22 20 66 6c 61 67 2e 20 54 68 69 73 20 68 61  a" flag. This ha
1b8c0 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63  s the same effec
1b8d0 74 20 61 6e 64 20 69 73 20 6c 6f 67 69 63 61 6c  t and is logical
1b8e0 6c 79 20 65 71 75 69 76 61 6c 65 6e 74 0a 2a 2a  ly equivalent.**
1b8f0 20 74 6f 20 73 65 74 74 69 6e 67 20 5b 50 52 41   to setting [PRA
1b900 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68  GMA writable_sch
1b910 65 6d 61 3d 4f 4e 5d 20 6f 72 20 5b 50 52 41 47  ema=ON] or [PRAG
1b920 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65  MA writable_sche
1b930 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a 20 54 68 65 20  ma=OFF]..** The 
1b940 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1b950 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  o this setting i
1b960 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
1b970 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
1b980 6c 65 20 0a 2a 2a 20 74 68 65 20 77 72 69 74 61  le .** the writa
1b990 62 6c 65 5f 73 63 68 65 6d 61 2c 20 70 6f 73 69  ble_schema, posi
1b9a0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 77  tive to enable w
1b9b0 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20  ritable_schema, 
1b9c0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 0a 2a  or negative to.*
1b9d0 2a 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  * leave the sett
1b9e0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 20 54  ing unchanged. T
1b9f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1ba00 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1ba10 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   to an.** intege
1ba20 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20  r into which is 
1ba30 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
1ba40 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1ba50 65 72 20 74 68 65 20 77 72 69 74 61 62 6c 65 5f  er the writable_
1ba60 73 63 68 65 6d 61 0a 2a 2a 20 69 73 20 65 6e 61  schema.** is ena
1ba70 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
1ba80 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
1ba90 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  call..** </dd>.*
1baa0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42  *.** [[SQLITE_DB
1bab0 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41 4c  CONFIG_LEGACY_AL
1bac0 54 45 52 5f 54 41 42 4c 45 5d 5d 0a 2a 2a 20 3c  TER_TABLE]].** <
1bad0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1bae0 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54 45 52 5f  IG_LEGACY_ALTER_
1baf0 54 41 42 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TABLE</dt>.** <d
1bb00 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43  d>The SQLITE_DBC
1bb10 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54  ONFIG_LEGACY_ALT
1bb20 45 52 5f 54 41 42 4c 45 20 6f 70 74 69 6f 6e 20  ER_TABLE option 
1bb30 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61  activates or dea
1bb40 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20  ctivates.** the 
1bb50 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1bb60 6f 66 20 74 68 65 20 5b 41 4c 54 45 52 20 54 41  of the [ALTER TA
1bb70 42 4c 45 20 52 45 4e 41 4d 45 5d 20 63 6f 6d 6d  BLE RENAME] comm
1bb80 61 6e 64 20 73 75 63 68 20 69 74 0a 2a 2a 20 62  and such it.** b
1bb90 65 68 61 76 65 73 20 61 73 20 69 74 20 64 69 64  ehaves as it did
1bba0 20 70 72 69 6f 72 20 74 6f 20 5b 76 65 72 73 69   prior to [versi
1bbb0 6f 6e 20 33 2e 32 34 2e 30 5d 20 28 32 30 31 38  on 3.24.0] (2018
1bbc0 2d 30 36 2d 30 34 29 2e 20 20 53 65 65 20 74 68  -06-04).  See th
1bbd0 65 0a 2a 2a 20 22 43 6f 6d 70 61 74 69 62 69 6c  e.** "Compatibil
1bbe0 69 74 79 20 4e 6f 74 69 63 65 22 20 6f 6e 20 74  ity Notice" on t
1bbf0 68 65 20 5b 41 4c 54 45 52 20 54 41 42 4c 45 20  he [ALTER TABLE 
1bc00 52 45 4e 41 4d 45 20 64 6f 63 75 6d 65 6e 74 61  RENAME documenta
1bc10 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64  tion] for.** add
1bc20 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
1bc30 69 6f 6e 2e 20 54 68 69 73 20 66 65 61 74 75 72  ion. This featur
1bc40 65 20 63 61 6e 20 61 6c 73 6f 20 62 65 20 74 75  e can also be tu
1bc50 72 6e 65 64 20 6f 6e 20 61 6e 64 20 6f 66 66 0a  rned on and off.
1bc60 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 50 52  ** using the [PR
1bc70 41 47 4d 41 20 6c 65 67 61 63 79 5f 61 6c 74 65  AGMA legacy_alte
1bc80 72 5f 74 61 62 6c 65 5d 20 73 74 61 74 65 6d 65  r_table] stateme
1bc90 6e 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  nt..** </dd>.**.
1bca0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
1bcb0 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 5d 5d 0a 2a  NFIG_DQS_DML]].*
1bcc0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
1bcd0 4f 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 3c 2f 74  ONFIG_DQS_DML</t
1bce0 64 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  d>.** <dd>The SQ
1bcf0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51  LITE_DBCONFIG_DQ
1bd00 53 5f 44 4d 4c 20 6f 70 74 69 6f 6e 20 61 63 74  S_DML option act
1bd10 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69  ivates or deacti
1bd20 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 6c 65 67  vates.** the leg
1bd30 61 63 79 20 5b 64 6f 75 62 6c 65 2d 71 75 6f 74  acy [double-quot
1bd40 65 64 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ed string litera
1bd50 6c 5d 20 6d 69 73 66 65 61 74 75 72 65 20 66 6f  l] misfeature fo
1bd60 72 20 44 4d 4c 20 73 74 61 74 65 6d 65 6e 74 0a  r DML statement.
1bd70 2a 2a 20 6f 6e 6c 79 2c 20 74 68 61 74 20 69 73  ** only, that is
1bd80 20 44 45 4c 45 54 45 2c 20 49 4e 53 45 52 54 2c   DELETE, INSERT,
1bd90 20 53 45 4c 45 43 54 2c 20 61 6e 64 20 55 50 44   SELECT, and UPD
1bda0 41 54 45 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  ATE statements. 
1bdb0 54 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 76  The.** default v
1bdc0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 73 65 74  alue of this set
1bdd0 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
1bde0 65 64 20 62 79 20 74 68 65 20 5b 2d 44 53 51 4c  ed by the [-DSQL
1bdf0 49 54 45 5f 44 51 53 5d 0a 2a 2a 20 63 6f 6d 70  ITE_DQS].** comp
1be00 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
1be10 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1be20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
1be30 47 5f 44 51 53 5f 44 44 4c 5d 5d 0a 2a 2a 20 3c  G_DQS_DDL]].** <
1be40 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1be50 49 47 5f 44 51 53 5f 44 44 4c 3c 2f 74 64 3e 0a  IG_DQS_DDL</td>.
1be60 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
1be70 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 20 6f  E_DBCONFIG_DQS o
1be80 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20  ption activates 
1be90 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a  or deactivates.*
1bea0 2a 20 74 68 65 20 6c 65 67 61 63 79 20 5b 64 6f  * the legacy [do
1beb0 75 62 6c 65 2d 71 75 6f 74 65 64 20 73 74 72 69  uble-quoted stri
1bec0 6e 67 20 6c 69 74 65 72 61 6c 5d 20 6d 69 73 66  ng literal] misf
1bed0 65 61 74 75 72 65 20 66 6f 72 20 44 44 4c 20 73  eature for DDL s
1bee0 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 73 75  tatements,.** su
1bef0 63 68 20 61 73 20 43 52 45 41 54 45 20 54 41 42  ch as CREATE TAB
1bf00 4c 45 20 61 6e 64 20 43 52 45 41 54 45 20 49 4e  LE and CREATE IN
1bf10 44 45 58 2e 20 54 68 65 0a 2a 2a 20 64 65 66 61  DEX. The.** defa
1bf20 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 74 68 69  ult value of thi
1bf30 73 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  s setting is det
1bf40 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b  ermined by the [
1bf50 2d 44 53 51 4c 49 54 45 5f 44 51 53 5d 0a 2a 2a  -DSQLITE_DQS].**
1bf60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1bf70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tion..** </dd>.*
1bf80 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
1bf90 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1bfa0 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20  IG_MAINDBNAME   
1bfb0 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a           1000 /*
1bfc0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a   const char* */.
1bfd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bfe0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
1bff0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30  E             10
1c000 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  01 /* void* int 
1c010 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
1c020 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1c030 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20  NABLE_FKEY      
1c040 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74       1002 /* int
1c050 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1c060 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1c070 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
1c080 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69         1003 /* i
1c090 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1c0a0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1c0b0 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
1c0c0 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a  OKENIZER 1004 /*
1c0d0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1c0e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1c0f0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
1c100 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20  _EXTENSION 1005 
1c110 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1c120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1c130 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f  CONFIG_NO_CKPT_O
1c140 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30  N_CLOSE      100
1c150 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  6 /* int int* */
1c160 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c170 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1c180 51 50 53 47 20 20 20 20 20 20 20 20 20 20 20 31  QPSG           1
1c190 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  007 /* int int* 
1c1a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c1b0 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47  E_DBCONFIG_TRIGG
1c1c0 45 52 5f 45 51 50 20 20 20 20 20 20 20 20 20 20  ER_EQP          
1c1d0 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 69 6e 74   1008 /* int int
1c1e0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1c1f0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1c200 45 54 5f 44 41 54 41 42 41 53 45 20 20 20 20 20  ET_DATABASE     
1c210 20 20 20 31 30 30 39 20 2f 2a 20 69 6e 74 20 69     1009 /* int i
1c220 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1c230 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44  QLITE_DBCONFIG_D
1c240 45 46 45 4e 53 49 56 45 20 20 20 20 20 20 20 20  EFENSIVE        
1c250 20 20 20 20 20 31 30 31 30 20 2f 2a 20 69 6e 74       1010 /* int
1c260 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1c270 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1c280 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45 4d 41  _WRITABLE_SCHEMA
1c290 20 20 20 20 20 20 20 31 30 31 31 20 2f 2a 20 69         1011 /* i
1c2a0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1c2b0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1c2c0 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54 45 52 5f  IG_LEGACY_ALTER_
1c2d0 54 41 42 4c 45 20 20 20 20 31 30 31 32 20 2f 2a  TABLE    1012 /*
1c2e0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1c2f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1c300 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 20 20 20 20  NFIG_DQS_DML    
1c310 20 20 20 20 20 20 20 20 20 20 20 31 30 31 33 20             1013 
1c320 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1c330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1c340 43 4f 4e 46 49 47 5f 44 51 53 5f 44 44 4c 20 20  CONFIG_DQS_DDL  
1c350 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 31               101
1c360 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  4 /* int int* */
1c370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c380 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20  DBCONFIG_MAX    
1c390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1c3a0 30 31 34 20 2f 2a 20 4c 61 72 67 65 73 74 20 44  014 /* Largest D
1c3b0 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a  BCONFIG */../*.*
1c3c0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
1c3d0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
1c3e0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
1c3f0 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
1c400 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1c410 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
1c420 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
1c430 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
1c440 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
1c450 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
1c460 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
1c470 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
1c480 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
1c490 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
1c4a0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
1c4b0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
1c4c0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
1c4d0 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
1c4e0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
1c4f0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
1c500 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
1c510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c520 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
1c530 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1c540 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
1c550 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
1c560 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
1c570 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
1c580 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
1c590 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
1c5a0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
1c5b0 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
1c5c0 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
1c5d0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
1c5e0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
1c5f0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
1c600 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
1c610 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
1c620 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
1c630 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
1c640 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
1c650 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
1c660 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
1c670 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
1c680 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
1c690 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
1c6a0 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
1c6b0 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
1c6c0 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
1c6d0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
1c6e0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
1c6f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c700 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1c710 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
1c720 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73   usually returns
1c730 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a   the [rowid] of.
1c740 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
1c750 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
1c760 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
1c770 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
1c780 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
1c790 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
1c7a0 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72  ection D. ^Inser
1c7b0 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
1c7c0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
1c7d0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64  re not.** record
1c7e0 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  ed. ^If no succe
1c7f0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
1c800 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
1c810 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
1c820 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20  rred .** on the 
1c830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c840 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69  ion D, then sqli
1c850 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1c860 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
1c870 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a   .** zero..**.**
1c880 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e   As well as bein
1c890 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61  g set automatica
1c8a0 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20  lly as rows are 
1c8b0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61  inserted into da
1c8c0 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73  tabase.** tables
1c8d0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1c8e0 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
1c8f0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74  ction may be set
1c900 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a   explicitly by.*
1c910 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  * [sqlite3_set_l
1c920 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1c930 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76  ()].**.** Some v
1c940 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
1c950 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
1c960 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74   INSERT rows int
1c970 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61  o rowid tables a
1c980 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d  s.** part of com
1c990 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61  mitting a transa
1c9a0 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66  ction (e.g. to f
1c9b0 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75  lush data accumu
1c9c0 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  lated in memory.
1c9d0 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20  ** to disk). In 
1c9e0 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71  this case subseq
1c9f0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68  uent calls to th
1ca00 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1ca10 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20  rn the rowid.** 
1ca20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1ca30 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49  these internal I
1ca40 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73  NSERT operations
1ca50 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f  , which leads to
1ca60 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65   .** unintuitive
1ca70 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61   results. Virtua
1ca80 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
1ca90 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20  tations that do 
1caa0 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a  write to rowid.*
1cab0 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73  * tables in this
1cac0 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74   way can avoid t
1cad0 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72  his problem by r
1cae0 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69  estoring the ori
1caf0 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20  ginal .** rowid 
1cb00 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c  value using [sql
1cb10 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1cb20 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65  sert_rowid()] be
1cb30 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a  fore returning .
1cb40 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68  ** control to th
1cb50 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e user..**.** ^(
1cb60 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
1cb70 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
1cb80 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73  rigger then this
1cb90 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a   routine will .*
1cba0 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  * return the [ro
1cbb0 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
1cbc0 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67  rted row as long
1cbd0 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
1cbe0 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20  is .** running. 
1cbf0 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  Once the trigger
1cc00 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74   program ends, t
1cc10 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1cc20 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
1cc30 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
1cc40 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
1cc50 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
1cc60 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  was fired.)^.**.
1cc70 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
1cc80 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
1cc90 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
1cca0 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
1ccb0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
1ccc0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
1ccd0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
1cce0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1ccf0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
1cd00 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
1cd10 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
1cd20 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
1cd30 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
1cd40 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
1cd50 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
1cd60 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
1cd70 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1cd80 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
1cd90 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
1cda0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
1cdb0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
1cdc0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
1cdd0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
1cde0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
1cdf0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
1ce00 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
1ce10 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
1ce20 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
1ce30 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
1ce40 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
1ce50 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
1ce60 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1ce70 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
1ce80 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
1ce90 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1cea0 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
1ceb0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
1cec0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
1ced0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
1cee0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
1cef0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
1cf00 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
1cf10 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
1cf20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
1cf30 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1cf40 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
1cf50 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
1cf60 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
1cf70 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1cf80 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1cf90 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1cfa0 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
1cfb0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
1cfc0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
1cfd0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1cfe0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
1cff0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
1d000 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1d010 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
1d020 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
1d030 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
1d040 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
1d050 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
1d060 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
1d070 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1d080 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
1d090 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
1d0a0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
1d0b0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
1d0c0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
1d0d0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1d0e0 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
1d0f0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
1d100 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1d110 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1d120 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1d130 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74   the Last Insert
1d140 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a   Rowid value..**
1d150 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1d160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1d170 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1d180 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d  rt_rowid(D, R) m
1d190 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65  ethod allows the
1d1a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
1d1b0 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ** set the value
1d1c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c   returned by cal
1d1d0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73  ling sqlite3_las
1d1e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1d1f0 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f  ) to R .** witho
1d200 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72  ut inserting a r
1d210 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  ow into the data
1d220 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  base..*/.void sq
1d230 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1d240 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1d250 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  te3*,sqlite3_int
1d260 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
1d270 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
1d280 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
1d290 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
1d2a0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1d2b0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1d2c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1d2d0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1d2e0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
1d2f0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
1d300 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
1d310 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
1d320 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1d330 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
1d340 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
1d350 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
1d360 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
1d370 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
1d380 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1d390 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1d3a0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
1d3b0 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
1d3c0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1d3d0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
1d3e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
1d3f0 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
1d400 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
1d410 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1d420 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
1d430 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
1d440 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
1d450 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
1d460 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
1d470 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
1d480 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
1d490 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
1d4a0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
1d4b0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
1d4c0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
1d4d0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
1d4e0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1d4f0 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
1d500 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1d510 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
1d520 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
1d530 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
1d540 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
1d550 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1d560 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
1d570 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
1d580 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
1d590 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
1d5a0 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
1d5b0 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
1d5c0 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
1d5d0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
1d5e0 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
1d5f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
1d600 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
1d610 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
1d620 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1d630 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
1d640 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
1d650 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
1d660 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
1d670 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
1d680 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
1d690 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
1d6a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
1d6b0 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
1d6c0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1d6d0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
1d6e0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1d6f0 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
1d700 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
1d710 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
1d720 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
1d730 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1d740 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1d750 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1d760 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1d770 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
1d780 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
1d790 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1d7a0 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
1d7b0 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
1d7c0 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
1d7d0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
1d7e0 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
1d7f0 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
1d800 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
1d810 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
1d820 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
1d830 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
1d840 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1d850 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1d860 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1d870 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
1d880 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
1d890 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
1d8a0 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
1d8b0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
1d8c0 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
1d8d0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
1d8e0 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
1d8f0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1d900 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
1d910 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
1d920 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
1d930 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
1d940 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
1d950 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
1d960 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
1d970 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
1d980 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
1d990 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
1d9a0 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
1d9b0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1d9c0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1d9d0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1d9e0 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
1d9f0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
1da00 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
1da10 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
1da20 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
1da30 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
1da40 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1da50 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
1da60 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
1da70 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
1da80 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
1da90 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
1daa0 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
1dab0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1dac0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
1dad0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
1dae0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1daf0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1db00 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
1db10 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  r..**.** If a se
1db20 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1db30 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1db40 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1db50 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1db60 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
1db70 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1db80 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1db90 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
1dba0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1dbb0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1dbc0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ul..**.** See al
1dbd0 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  so:.** <ul>.** <
1dbe0 6c 69 3e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  li> the [sqlite3
1dbf0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1dc00 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c  ] interface.** <
1dc10 6c 69 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63  li> the [count_c
1dc20 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a  hanges pragma].*
1dc30 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e  * <li> the [chan
1dc40 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1dc50 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  on].** <li> the 
1dc60 5b 64 61 74 61 5f 76 65 72 73 69 6f 6e 20 70 72  [data_version pr
1dc70 61 67 6d 61 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  agma].** </ul>.*
1dc80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
1dc90 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1dca0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dcb0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
1dcc0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1dcd0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1dce0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1dcf0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1dd00 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
1dd10 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
1dd20 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
1dd30 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
1dd40 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
1dd50 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1dd60 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
1dd70 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
1dd80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1dd90 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
1dda0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
1ddb0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
1ddc0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
1ddd0 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
1dde0 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1ddf0 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1de00 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
1de10 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
1de20 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1de30 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1de40 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
1de50 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
1de60 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
1de70 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
1de80 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
1de90 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
1dea0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
1deb0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
1dec0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1ded0 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
1dee0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
1def0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1df00 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
1df10 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
1df20 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
1df30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  ed..**.** The [s
1df40 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1df50 6e 67 65 73 28 44 29 5d 20 69 6e 74 65 72 66 61  nges(D)] interfa
1df60 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
1df70 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
1df80 20 72 6f 77 73 20 74 68 61 74 20 63 68 61 6e 67   rows that chang
1df90 65 64 20 64 75 65 20 74 6f 20 53 51 4c 20 73 74  ed due to SQL st
1dfa0 61 74 65 6d 65 6e 74 20 72 75 6e 20 61 67 61 69  atement run agai
1dfb0 6e 73 74 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  nst database.** 
1dfc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1dfd0 6e 79 20 63 68 61 6e 67 65 73 20 62 79 20 6f 74  ny changes by ot
1dfe0 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  her database con
1dff0 6e 65 63 74 69 6f 6e 73 20 61 72 65 20 69 67 6e  nections are ign
1e000 6f 72 65 64 2e 0a 2a 2a 20 54 6f 20 64 65 74 65  ored..** To dete
1e010 63 74 20 63 68 61 6e 67 65 73 20 61 67 61 69 6e  ct changes again
1e020 73 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  st a database fi
1e030 6c 65 20 66 72 6f 6d 20 6f 74 68 65 72 20 64 61  le from other da
1e040 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
1e050 74 69 6f 6e 73 20 75 73 65 20 74 68 65 20 5b 50  tions use the [P
1e060 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72 73 69  RAGMA data_versi
1e070 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 6f 72 20 74  on] command or t
1e080 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
1e090 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e  NTL_DATA_VERSION
1e0a0 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d  ] [file control]
1e0b0 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 61 20 73 65  ..** .** If a se
1e0c0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1e0d0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1e0e0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1e0f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1e100 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
1e110 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
1e120 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1e130 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
1e140 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
1e150 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1e160 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20  aningful..**.** 
1e170 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c  See also:.** <ul
1e180 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73  >.** <li> the [s
1e190 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1e1a0 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c  ] interface.** <
1e1b0 6c 69 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63  li> the [count_c
1e1c0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a  hanges pragma].*
1e1d0 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e  * <li> the [chan
1e1e0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1e1f0 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  on].** <li> the 
1e200 5b 64 61 74 61 5f 76 65 72 73 69 6f 6e 20 70 72  [data_version pr
1e210 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68  agma].** <li> th
1e220 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
1e230 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20 5b 66  DATA_VERSION] [f
1e240 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d 0a 2a 2a 20  ile control].** 
1e250 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  </ul>.*/.int sql
1e260 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1e270 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1e280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
1e290 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
1e2a0 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
1e2b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1e2c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1e2d0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
1e2e0 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
1e2f0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
1e300 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
1e310 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
1e320 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
1e330 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
1e340 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
1e350 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
1e360 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
1e370 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
1e380 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
1e390 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
1e3a0 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
1e3b0 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
1e3c0 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
1e3d0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
1e3e0 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
1e3f0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1e400 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
1e410 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
1e420 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
1e430 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
1e440 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
1e450 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
1e460 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
1e470 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
1e480 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1e490 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1e4a0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
1e4b0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
1e4c0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
1e4d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1e4e0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
1e4f0 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
1e500 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
1e510 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
1e520 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
1e530 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
1e540 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
1e550 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
1e560 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
1e570 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
1e580 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
1e590 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
1e5a0 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
1e5b0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
1e5c0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
1e5d0 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
1e5e0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
1e5f0 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
1e600 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
1e610 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
1e620 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
1e630 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1e640 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
1e650 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
1e660 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
1e670 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
1e680 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
1e690 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
1e6a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
1e6b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e6c0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
1e6d0 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
1e6e0 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
1e6f0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
1e700 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
1e710 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
1e720 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
1e730 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
1e740 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1e750 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1e760 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1e770 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1e780 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
1e790 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
1e7a0 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
1e7b0 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
1e7c0 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
1e7d0 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
1e7e0 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
1e7f0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1e800 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
1e810 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1e820 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1e830 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1e840 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1e850 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
1e860 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
1e870 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
1e880 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1e890 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
1e8a0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
1e8b0 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
1e8c0 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
1e8d0 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
1e8e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1e8f0 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
1e900 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
1e910 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1e920 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1e930 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1e940 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1e950 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
1e960 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
1e970 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
1e980 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1e990 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
1e9a0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
1e9b0 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
1e9c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1e9d0 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
1e9e0 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
1e9f0 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
1ea00 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
1ea10 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
1ea20 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
1ea30 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
1ea40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
1ea50 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
1ea60 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
1ea70 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
1ea80 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
1ea90 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
1eaa0 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
1eab0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
1eac0 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
1ead0 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
1eae0 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
1eaf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1eb00 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
1eb10 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
1eb20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
1eb30 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
1eb40 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
1eb50 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
1eb60 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
1eb70 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
1eb80 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
1eb90 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
1eba0 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
1ebb0 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
1ebc0 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
1ebd0 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
1ebe0 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
1ebf0 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
1ec00 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
1ec10 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
1ec20 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
1ec30 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
1ec40 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
1ec50 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
1ec60 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
1ec70 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
1ec80 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
1ec90 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
1eca0 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
1ecb0 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
1ecc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1ecd0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
1ece0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
1ecf0 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
1ed00 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
1ed10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
1ed20 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
1ed30 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
1ed40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1ed50 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
1ed60 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
1ed70 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
1ed80 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
1ed90 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
1eda0 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
1edb0 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
1edc0 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
1edd0 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
1ede0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1edf0 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
1ee00 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
1ee10 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1ee20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
1ee30 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
1ee40 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
1ee50 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
1ee60 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
1ee70 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
1ee80 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
1ee90 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
1eea0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
1eeb0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1eec0 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
1eed0 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
1eee0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1eef0 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
1ef00 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
1ef10 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1ef20 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1ef30 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
1ef40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1ef50 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
1ef60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
1ef70 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1ef80 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
1ef90 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1efa0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
1efb0 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
1efc0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
1efd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1efe0 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
1eff0 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
1f000 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
1f010 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
1f020 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f030 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
1f040 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
1f050 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
1f060 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1f070 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
1f080 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
1f090 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  dler}.** METHOD:
1f0a0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1f0b0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1f0c0 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20  _handler(D,X,P) 
1f0d0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
1f0e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1f0f0 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74   X.** that might
1f100 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1f110 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
1f120 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
1f130 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  pt is made to ac
1f140 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20  cess a database 
1f150 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64  table associated
1f160 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61   with.** [databa
1f170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1f180 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68   when another th
1f190 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
1f1a0 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65  ss has the table
1f1b0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20   locked..** The 
1f1c0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1f1d0 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  dler() interface
1f1e0 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   is used to impl
1f1f0 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65  ement.** [sqlite
1f200 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1f210 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75  ] and [PRAGMA bu
1f220 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a  sy_timeout]..**.
1f230 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
1f240 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1f250 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
1f260 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  USY].** is retur
1f270 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
1f280 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
1f290 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
1f2a0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1f2b0 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
1f2c0 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
1f2d0 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
1f2e0 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
1f2f0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
1f300 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1f310 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
1f320 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
1f330 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
1f340 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
1f350 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
1f360 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1f370 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
1f380 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
1f390 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
1f3a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
1f3b0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
1f3c0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
1f3d0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
1f3e0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
1f3f0 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73  invoked previous
1f400 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ly for the same 
1f410 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
1f420 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
1f430 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1f440 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
1f450 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
1f460 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
1f470 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1f480 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
1f490 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
1f4a0 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1f4b0 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
1f4c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1f4d0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1f4e0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
1f4f0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
1f500 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1f510 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
1f520 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
1f530 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
1f540 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
1f550 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
1f560 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
1f570 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
1f580 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
1f590 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
1f5a0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
1f5b0 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
1f5c0 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
1f5d0 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
1f5e0 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
1f5f0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
1f600 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
1f610 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
1f620 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1f630 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
1f640 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
1f650 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
1f660 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
1f670 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
1f680 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1f690 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
1f6a0 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
1f6b0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1f6c0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
1f6d0 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
1f6e0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1f6f0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
1f700 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
1f710 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
1f720 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
1f730 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
1f740 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
1f750 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
1f760 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1f770 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1f780 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
1f790 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
1f7a0 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
1f7b0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1f7c0 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
1f7d0 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
1f7e0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
1f7f0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
1f800 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
1f810 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
1f820 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
1f830 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
1f840 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
1f850 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
1f860 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
1f870 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
1f880 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1f890 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
1f8a0 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
1f8b0 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
1f8c0 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
1f8d0 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
1f8e0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
1f8f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1f900 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1f910 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1f920 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1f930 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
1f940 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
1f950 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
1f960 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
1f970 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
1f980 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
1f990 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
1f9a0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
1f9b0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
1f9c0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
1f9d0 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
1f9e0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1f9f0 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
1fa00 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
1fa10 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
1fa20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
1fa30 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
1fa40 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1fa50 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1fa60 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1fa70 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1fa80 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1fa90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1faa0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1fab0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1fac0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
1fad0 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
1fae0 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
1faf0 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
1fb00 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
1fb10 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
1fb20 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
1fb30 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
1fb40 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
1fb50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1fb60 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
1fb70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1fb80 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
1fb90 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1fba0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
1fbb0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1fbc0 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76  qlite3*,int(*)(v
1fbd0 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29  oid*,int),void*)
1fbe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fbf0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
1fc00 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meout.** METHOD:
1fc10 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1fc20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1fc30 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1fc40 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1fc50 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1fc60 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1fc70 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1fc80 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1fc90 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1fca0 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1fcb0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1fcc0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1fcd0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1fce0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1fcf0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1fd00 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1fd10 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1fd20 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1fd30 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1fd40 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1fd50 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1fd60 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1fd70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1fd80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
1fd90 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1fda0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1fdb0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1fdc0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1fdd0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1fde0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1fdf0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1fe00 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1fe10 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1fe20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1fe30 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1fe40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fe50 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
1fe60 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1fe70 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1fe80 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1fe90 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1fea0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1feb0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1fec0 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1fed0 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1fee0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1fef0 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
1ff00 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
1ff10 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
1ff20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1ff30 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1ff40 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1ff50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ff60 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1ff70 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1ff80 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1ff90 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1ffa0 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1ffb0 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1ffc0 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1ffd0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1ffe0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1fff0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
20000 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
20010 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
20020 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
20030 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
20040 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
20050 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
20060 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
20070 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
20080 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
20090 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
200a0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
200b0 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
200c0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
200d0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
200e0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
200f0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
20100 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
20110 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
20120 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
20130 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
20140 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
20150 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
20160 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
20170 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
20180 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
20190 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
201a0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
201b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
201c0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
201d0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
201e0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
201f0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
20200 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
20210 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
20220 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
20230 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
20240 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
20250 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
20260 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
20270 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
20280 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
20290 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
202a0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
202b0 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
202c0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
202d0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
202e0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
202f0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
20300 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
20310 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
20320 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
20330 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
20340 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
20350 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
20360 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
20370 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
20380 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
20390 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
203a0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
203b0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
203c0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
203d0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
203e0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
203f0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
20400 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
20410 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
20420 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
20430 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
20440 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
20450 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
20460 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
20470 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
20480 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
20490 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
204a0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
204b0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
204c0 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
204d0 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
204e0 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
204f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
20500 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
20510 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
20520 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
20530 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
20540 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
20550 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
20560 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
20570 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
20580 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
20590 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
205a0 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
205b0 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
205c0 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
205d0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
205e0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
205f0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
20600 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
20610 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
20620 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
20630 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
20640 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
20650 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
20660 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
20670 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
20680 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
20690 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
206a0 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
206b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
206c0 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
206d0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
206e0 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
206f0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
20700 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
20710 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
20720 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
20730 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
20740 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
20750 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
20760 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
20770 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
20780 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
20790 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
207a0 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
207b0 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
207c0 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
207d0 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
207e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
207f0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
20800 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
20810 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
20820 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
20830 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
20840 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
20850 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
20860 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
20870 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
20880 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
20890 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
208a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
208b0 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
208c0 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
208d0 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
208e0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
208f0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
20900 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
20910 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
20920 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
20930 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
20940 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
20950 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
20960 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
20970 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
20980 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
20990 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
209a0 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
209b0 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
209c0 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
209d0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
209e0 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
209f0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
20a00 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
20a10 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
20a20 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
20a30 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
20a40 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
20a50 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
20a60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
20a70 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
20a80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
20a90 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
20aa0 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
20ab0 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
20ac0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
20ad0 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
20ae0 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
20af0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
20b00 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
20b10 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
20b20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
20b30 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
20b40 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
20b50 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
20b60 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
20b70 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
20b80 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
20b90 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
20ba0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
20bb0 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
20bc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
20bd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20be0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
20bf0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
20c00 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
20c10 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
20c20 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
20c30 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
20c40 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
20c50 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
20c60 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
20c70 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
20c80 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
20c90 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
20ca0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
20cb0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
20cc0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
20cd0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
20ce0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
20cf0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
20d00 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
20d10 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
20d20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
20d30 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
20d40 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
20d50 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
20d60 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
20d70 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
20d80 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
20d90 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
20da0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
20db0 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
20dc0 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
20dd0 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
20de0 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
20df0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
20e00 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
20e10 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
20e20 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
20e30 6d 6d 6f 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20  mmon formatting 
20e40 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20  options from.** 
20e50 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62  the standard lib
20e60 72 61 72 79 20 70 72 69 6e 74 66 28 29 20 0a 2a  rary printf() .*
20e70 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
20e80 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
20e90 61 72 64 20 66 6f 72 6d 61 74 73 20 28 5b 25 71  ard formats ([%q
20ea0 5d 2c 20 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61  ], [%Q], [%w], a
20eb0 6e 64 20 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65  nd [%z])..** See
20ec0 20 74 68 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70   the [built-in p
20ed0 72 69 6e 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e  rintf()] documen
20ee0 74 61 74 69 6f 6e 20 66 6f 72 20 64 65 74 61 69  tation for detai
20ef0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ls..**.** ^The s
20f00 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
20f10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
20f20 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
20f30 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
20f40 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
20f50 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
20f60 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
20f70 63 36 34 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  c64()]..** The s
20f80 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
20f90 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
20fa0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
20fb0 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
20fc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
20fd0 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
20fe0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
20ff0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
21000 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
21010 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
21020 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
21030 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
21040 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
21050 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
21060 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
21070 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
21080 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
21090 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
210a0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
210b0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
210c0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
210d0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
210e0 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
210f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
21100 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
21110 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
21120 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
21130 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
21140 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
21150 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
21160 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
21170 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
21180 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
21190 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
211a0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
211b0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
211c0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
211d0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
211e0 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
211f0 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
21200 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
21210 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
21220 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
21230 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
21240 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
21250 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
21260 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
21270 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
21280 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
21290 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
212a0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
212b0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
212c0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
212d0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
212e0 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
212f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
21300 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
21310 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
21320 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
21330 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
21340 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
21350 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
21360 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
21370 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
21380 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
21390 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
213a0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
213b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
213c0 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
213d0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
213e0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
213f0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
21400 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
21410 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
21420 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
21430 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
21440 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
21450 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
21460 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
21470 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
21480 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
21490 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
214a0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
214b0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
214c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
214d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
214e0 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28  built-in printf(
214f0 29 5d 2c 20 5b 70 72 69 6e 74 66 28 29 20 53 51  )], [printf() SQ
21500 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63  L function].*/.c
21510 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
21520 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
21530 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
21540 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
21550 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
21560 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
21570 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
21580 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21590 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  *, ...);.char *s
215a0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
215b0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
215c0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
215d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
215e0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
215f0 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
21600 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
21610 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
21620 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
21630 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
21640 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
21650 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
21660 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
21670 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
21680 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
21690 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
216a0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
216b0 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
216c0 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
216d0 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
216e0 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
216f0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
21700 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
21710 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
21720 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
21730 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
21740 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
21750 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
21760 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
21770 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
21780 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
21790 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
217a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
217b0 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
217c0 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
217d0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
217e0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
217f0 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
21800 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
21810 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
21820 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
21830 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
21840 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
21850 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
21860 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
21870 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
21880 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20  oc64(N) routine 
21890 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a  works just like.
218a0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
218b0 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  c(N) except that
218c0 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65   N is an unsigne
218d0 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  d 64-bit integer
218e0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
218f0 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69   signed 32-bit i
21900 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  nteger..**.** ^C
21910 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
21920 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
21930 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
21940 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
21950 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
21960 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
21970 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
21980 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
21990 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
219a0 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
219b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
219c0 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
219d0 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
219e0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
219f0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
21a00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
21a10 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
21a20 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
21a30 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
21a40 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
21a50 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
21a60 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
21a70 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
21a80 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
21a90 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
21aa0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
21ab0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
21ac0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
21ad0 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
21ae0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
21af0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
21b00 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
21b10 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
21b20 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
21b30 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
21b40 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
21b50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
21b60 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
21b70 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
21b80 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
21b90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
21ba0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
21bb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
21bc0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
21bd0 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
21be0 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
21bf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f   allocation X to
21c00 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
21c10 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
21c20 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   X parameter to 
21c30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21c40 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  X,N).** is a NUL
21c50 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
21c60 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
21c70 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
21c80 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
21c90 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66  alloc(N)..** ^If
21ca0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
21cb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
21cc0 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f  loc(X,N) is zero
21cd0 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
21ce0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
21cf0 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
21d00 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
21d10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
21d20 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  (X)..** ^sqlite3
21d30 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
21d40 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
21d50 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
21d60 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
21d70 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
21d80 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
21d90 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
21da0 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c  mory is availabl
21db0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
21dc0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
21dd0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
21de0 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
21df0 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
21e00 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
21e10 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
21e20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
21e30 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
21e40 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
21e50 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20  ealloc(X,N) and 
21e60 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
21e70 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
21e80 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
21e90 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
21ea0 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73  ns NULL and N is
21eb0 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
21ec0 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c  the.** prior all
21ed0 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66  ocation is not f
21ee0 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  reed..**.** ^The
21ef0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
21f00 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  64(X,N) interfac
21f10 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  es works the sam
21f20 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
21f30 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63  realloc(X,N) exc
21f40 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20  ept that N is a 
21f50 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
21f60 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
21f70 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73  ** of a 32-bit s
21f80 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
21f90 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20  *.** ^If X is a 
21fa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
21fb0 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  n previously obt
21fc0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
21fd0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  e3_malloc(),.** 
21fe0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
21ff0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
22000 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  loc(), or sqlite
22010 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74  3_realloc64(), t
22020 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
22030 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
22040 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74  the size of that
22050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
22060 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20  on in bytes..** 
22070 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
22080 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
22090 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65  size(X) might be
220a0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
220b0 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79   number.** of by
220c0 74 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68  tes requested wh
220d0 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74  en X was allocat
220e0 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20  ed.  ^If X is a 
220f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
22100 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
22110 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65  ze(X) returns ze
22120 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73  ro.  If X points
22130 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68   to something th
22140 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65  at is not.** the
22150 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65   beginning of me
22160 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  mory allocation,
22170 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73   or if it points
22180 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a   to a formerly.*
22190 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61  * valid memory a
221a0 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68  llocation that h
221b0 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65  as now been free
221c0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
221d0 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  vior.** of sqlit
221e0 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75  e3_msize(X) is u
221f0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73  ndefined and pos
22200 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  sibly harmful..*
22210 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
22220 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
22230 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73  ite3_malloc(), s
22240 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
22250 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
22260 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c  loc64(), and sql
22270 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
22280 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
22290 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
222a0 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
222b0 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
222c0 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
222d0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
222e0 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
222f0 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
22300 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
22310 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
22320 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
22330 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
22340 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
22350 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
22360 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
22370 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
22380 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
22390 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
223a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
223b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
223c0 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
223d0 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
223e0 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
223f0 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
22400 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
22410 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
22420 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
22430 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
22440 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20  version 3.7.10, 
22450 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  the Windows OS i
22460 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
22470 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73  alled.** the sys
22480 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
22490 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
224a0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
224b0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
224c0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
224d0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
224e0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
224f0 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
22500 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
22510 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
22520 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
22530 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
22540 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
22550 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65  errors were dete
22560 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
22570 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20  y were reported 
22580 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
22590 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
225a0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
225b0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
225c0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
225d0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
225e0 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
225f0 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
22600 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
22610 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
22620 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
22630 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
22640 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
22650 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
22660 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
22670 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
22680 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
22690 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
226a0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
226b0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
226c0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
226d0 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
226e0 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
226f0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
22700 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
22710 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
22720 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
22730 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
22740 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
22750 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
22760 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
22770 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
22780 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
22790 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
227a0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
227b0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
227c0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64  3_realloc64(void
227d0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
227e0 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
227f0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71  _free(void*);.sq
22800 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c  lite3_uint64 sql
22810 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a  ite3_msize(void*
22820 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22830 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
22840 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
22850 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
22860 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
22870 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
22880 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
22890 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
228a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
228b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
228c0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
228d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
228e0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
228f0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
22900 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
22910 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
22920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
22930 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
22940 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
22950 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
22960 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
22970 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
22980 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
22990 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
229a0 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
229b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
229c0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
229d0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
229e0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
229f0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
22a00 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
22a10 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
22a20 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
22a30 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
22a40 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
22a50 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
22a60 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
22a70 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
22a80 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
22a90 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
22aa0 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
22ab0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
22ac0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
22ad0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
22ae0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
22af0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
22b00 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
22b10 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
22b20 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
22b30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
22b40 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
22b50 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
22b60 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
22b70 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
22b80 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
22b90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
22ba0 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
22bb0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
22bc0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
22bd0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
22be0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
22bf0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
22c00 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
22c10 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
22c20 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
22c30 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
22c40 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
22c50 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
22c60 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
22c70 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
22c80 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
22c90 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
22ca0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
22cb0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
22cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22cd0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
22ce0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
22cf0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
22d00 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
22d10 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
22d20 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
22d30 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
22d40 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
22d50 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
22d60 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
22d70 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
22d80 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
22d90 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
22da0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
22db0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
22dc0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
22dd0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
22de0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
22df0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
22e00 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
22e10 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
22e20 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
22e30 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
22e40 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
22e50 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
22e60 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
22e70 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
22e80 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
22e90 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
22ea0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
22eb0 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65  ** ^The P parame
22ec0 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c  ter can be a NUL
22ed0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
22ee0 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
22ef0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70  e has not been p
22f00 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64  reviously called
22f10 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69   or if the previ
22f20 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20  ous.** call had 
22f30 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  N less than one 
22f40 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
22f50 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68  r for P, then th
22f60 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65  e PRNG is.** see
22f70 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
22f80 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ness obtained fr
22f90 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
22fa0 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20  ss method of.** 
22fb0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
22fc0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
22fd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65  ..** ^If the pre
22fe0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
22ff0 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61  is routine had a
23000 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65  n N of 1 or more
23010 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55   and a.** non-NU
23020 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73  LL P then the ps
23030 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
23040 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
23050 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
23060 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
23070 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
23080 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
23090 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76  .** method..*/.v
230a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
230b0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
230c0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
230d0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
230e0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
230f0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
23100 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
23110 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
23120 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
23130 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ck}.**.** ^This 
23140 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
23150 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
23160 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
23170 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
23180 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23190 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
231a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
231b0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
231c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
231d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
231e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
231f0 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
23200 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
23210 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
23220 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
23230 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23240 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
23250 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
23260 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23270 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
23280 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a  epare16_v2()],.*
23290 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  * and [sqlite3_p
232a0 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 20  repare16_v3()]. 
232b0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
232c0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
232d0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
232e0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
232f0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
23300 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
23310 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
23320 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
23330 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
23340 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
23350 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
23360 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
23370 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
23380 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
23390 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
233a0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
233b0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
233c0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
233d0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
233e0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
233f0 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
23400 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
23410 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
23420 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
23430 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
23440 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
23450 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
23460 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
23470 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
23480 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
23490 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
234a0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
234b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
234c0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
234d0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
234e0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
234f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23500 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
23510 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
23520 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
23530 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
23540 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
23550 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
23560 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
23570 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
23580 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
23590 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
235a0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
235b0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
235c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
235d0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
235e0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
235f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
23600 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
23610 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
23620 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
23630 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
23640 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
23650 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
23660 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
23670 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
23680 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
23690 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
236a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
236b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
236c0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
236d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
236e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
236f0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
23700 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
23710 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
23720 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
23730 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
23740 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
23750 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
23760 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
23770 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
23780 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
23790 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
237a0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
237b0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
237c0 63 6b 20 61 72 65 20 65 69 74 68 65 72 20 4e 55  ck are either NU
237d0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a  LL pointers or z
237e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
237f0 74 72 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63  trings.** that c
23800 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
23810 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  l details about 
23820 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
23830 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20   authorized..** 
23840 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
23850 74 20 61 6c 77 61 79 73 20 62 65 20 70 72 65 70  t always be prep
23860 61 72 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65  ared to encounte
23870 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
23880 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   in any.** of th
23890 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
238a0 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
238b0 74 65 72 73 20 6f 66 20 74 68 65 20 61 75 74 68  ters of the auth
238c0 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61  orization callba
238d0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ck..**.** ^If th
238e0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
238f0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
23900 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
23910 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
23920 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
23930 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
23940 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
23950 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
23960 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
23970 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
23980 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
23990 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
239a0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
239b0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
239c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
239d0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
239e0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
239f0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
23a00 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
23a10 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
23a20 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
23a30 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
23a40 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
23a50 2a 2a 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65  ** ^When a table
23a60 20 69 73 20 72 65 66 65 72 65 6e 63 65 64 20 62   is referenced b
23a70 79 20 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74  y a [SELECT] but
23a80 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65   no column value
23a90 73 20 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74  s are.** extract
23aa0 65 64 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62  ed from that tab
23ab0 6c 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  le (for example 
23ac0 69 6e 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a  in a query like.
23ad0 2a 2a 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74  ** "SELECT count
23ae0 28 2a 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74  (*) FROM tab") t
23af0 68 65 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  hen the [SQLITE_
23b00 52 45 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72  READ] authorizer
23b10 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
23b20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
23b30 20 74 68 61 74 20 74 61 62 6c 65 20 77 69 74 68   that table with
23b40 20 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74   a column name t
23b50 68 61 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20  hat is an empty 
23b60 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
23b70 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
23b80 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
23b90 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
23ba0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
23bb0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
23bc0 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
23bd0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
23be0 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
23bf0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
23c00 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
23c10 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
23c20 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
23c30 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
23c40 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
23c50 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
23c60 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
23c70 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
23c80 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
23c90 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
23ca0 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
23cb0 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
23cc0 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
23cd0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
23ce0 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
23cf0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
23d00 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
23d10 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
23d20 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
23d30 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
23d40 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
23d50 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
23d60 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
23d70 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
23d80 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
23d90 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
23da0 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
23db0 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
23dc0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
23dd0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
23de0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
23df0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
23e00 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
23e10 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
23e20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
23e30 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
23e40 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
23e50 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
23e60 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
23e70 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
23e80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
23e90 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
23ea0 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
23eb0 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
23ec0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
23ed0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
23ee0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
23ef0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
23f00 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
23f10 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
23f20 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
23f30 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
23f40 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
23f50 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
23f60 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
23f70 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
23f80 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
23f90 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
23fa0 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
23fb0 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
23fc0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
23fd0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
23fe0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
23ff0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
24000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24010 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
24020 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
24030 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
24040 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
24050 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
24060 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
24070 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
24080 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
24090 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
240a0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
240b0 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
240c0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
240d0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
240e0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
240f0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
24100 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
24110 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24120 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
24130 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
24140 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
24150 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
24160 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
24170 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
24180 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
24190 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
241a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
241b0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
241c0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
241d0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
241e0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
241f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24200 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
24210 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
24220 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
24230 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
24240 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
24250 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24260 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
24270 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
24280 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
24290 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
242a0 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
242b0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
242c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
242d0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
242e0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
242f0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
24300 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
24310 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
24320 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
24330 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
24340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
24350 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
24360 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
24370 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
24380 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
24390 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
243a0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
243b0 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
243c0 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
243d0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
243e0 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
243f0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
24400 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
24410 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
24420 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
24430 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
24440 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
24450 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
24460 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
24470 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
24480 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
24490 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
244a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
244b0 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
244c0 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
244d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
244e0 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
244f0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
24500 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
24510 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
24520 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
24530 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
24540 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
24550 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
24560 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
24570 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
24580 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
24590 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
245a0 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
245b0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
245c0 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
245d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
245e0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
245f0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
24600 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
24610 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
24620 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
24630 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61  LITE_IGNORE is a
24640 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63  lso used as a [c
24650 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69  onflict resoluti
24660 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75  on mode].** retu
24670 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73  rned from the [s
24680 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63  qlite3_vtab_on_c
24690 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72  onflict()] inter
246a0 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
246b0 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
246c0 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
246d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
246e0 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
246f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
24700 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
24710 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
24720 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
24730 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
24740 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24750 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
24760 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
24770 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
24780 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
24790 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
247a0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
247b0 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
247c0 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
247d0 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
247e0 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
247f0 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
24800 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
24810 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
24820 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
24830 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
24840 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
24850 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
24860 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
24870 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
24880 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
24890 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
248a0 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
248b0 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
248c0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
248d0 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
248e0 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
248f0 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
24900 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
24910 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
24920 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
24930 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
24940 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
24950 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
24960 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
24970 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
24980 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
24990 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
249a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
249b0 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
249c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
249d0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
249e0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
249f0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
24a00 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
24a10 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
24a20 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
24a30 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
24a40 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
24a50 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
24a60 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24a70 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
24a80 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
24a90 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
24aa0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
24ab0 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
24ac0 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
24ad0 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
24ae0 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
24af0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
24b00 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
24b10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24b20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24b30 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
24b40 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
24b50 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
24b60 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
24b70 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
24b80 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
24b90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24ba0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24bb0 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
24bc0 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
24bd0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
24be0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
24bf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24c00 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
24c10 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
24c20 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
24c30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
24c40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24c50 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
24c60 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
24c70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
24c80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24c90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
24ca0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
24cb0 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
24cc0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
24cd0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
24ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
24cf0 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
24d00 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
24d10 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
24d20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24d30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
24d40 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
24d50 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
24d60 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
24d70 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
24d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
24d90 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
24da0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
24db0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
24dc0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24dd0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
24de0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
24df0 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
24e00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
24e10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
24e20 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
24e30 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
24e40 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
24e50 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
24e60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
24e70 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
24e80 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
24e90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24ea0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
24eb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24ec0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
24ed0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
24ee0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
24ef0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
24f00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24f10 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
24f20 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
24f30 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24f40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24f50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24f60 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
24f70 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
24f80 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
24f90 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24fa0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24fb0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
24fc0 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
24fd0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
24fe0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24ff0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
25000 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
25010 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
25020 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
25030 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
25040 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
25050 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
25060 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
25070 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
25080 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
25090 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
250a0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
250b0 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
250c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
250d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
250e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
250f0 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
25100 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
25110 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
25120 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
25130 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25140 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
25150 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
25160 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
25170 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
25180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
25190 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
251a0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
251b0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
251c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
251d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
251e0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
251f0 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
25200 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
25210 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
25220 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
25230 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
25240 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
25250 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
25260 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
25270 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
25280 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
25290 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
252a0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
252b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
252c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
252d0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
252e0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
252f0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
25300 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
25310 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
25320 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
25330 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
25340 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
25350 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
25360 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
25370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
25380 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
25390 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
253a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
253b0 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
253c0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
253d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
253e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
253f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
25400 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
25410 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
25420 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
25430 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
25440 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
25450 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
25460 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
25470 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
25480 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
25490 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
254a0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
254b0 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
254c0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
254d0 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
254e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
254f0 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
25500 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
25510 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
25520 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
25530 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
25540 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
25550 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
25560 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
25570 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25580 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20  _RECURSIVE      
25590 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55        33   /* NU
255a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
255b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
255c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
255d0 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
255e0 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
255f0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
25600 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ite3.**.** These
25610 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
25620 70 72 65 63 61 74 65 64 2e 20 55 73 65 20 74 68  precated. Use th
25630 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  e [sqlite3_trace
25640 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
25650 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74  .** instead of t
25660 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63  he routines desc
25670 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  ribed here..**.*
25680 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
25690 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
256a0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
256b0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
256c0 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
256d0 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
256e0 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
256f0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
25700 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
25710 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
25720 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
25730 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
25740 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
25750 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
25760 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
25770 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
25780 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
25790 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
257a0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
257b0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
257c0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
257d0 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
257e0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
257f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
25800 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
25810 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
25820 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
25830 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
25840 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
25850 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
25860 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
25870 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
25880 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
25890 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
258a0 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
258b0 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
258c0 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
258d0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  )^.**.** The [SQ
258e0 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
258f0 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
25900 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ime option can b
25910 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a  e used to limit.
25920 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** the length of
25930 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
25940 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20  r] expansion in 
25950 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71  the output of sq
25960 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a  lite3_trace()..*
25970 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
25980 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
25990 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
259a0 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
259b0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
259c0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
259d0 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
259e0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
259f0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
25a00 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
25a10 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
25a20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
25a30 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
25a40 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
25a50 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
25a60 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
25a70 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
25a80 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
25a90 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
25aa0 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
25ab0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
25ac0 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
25ad0 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
25ae0 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
25af0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
25b00 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
25b10 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
25b20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
25b30 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
25b40 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
25b50 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
25b60 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
25b70 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
25b80 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
25b90 49 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 65 69 74 68  Invoking.** eith
25ba0 65 72 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  er [sqlite3_trac
25bb0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
25bc0 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 77 69 6c  _trace_v2()] wil
25bd0 6c 20 63 61 6e 63 65 6c 20 74 68 65 0a 2a 2a 20  l cancel the.** 
25be0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
25bf0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52  ..*/.SQLITE_DEPR
25c00 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c  ECATED void *sql
25c10 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
25c20 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54  e3*,.   void(*xT
25c30 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
25c40 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
25c50 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
25c60 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TED void *sqlite
25c70 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
25c80 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
25c90 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
25ca0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
25cb0 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
25cc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25cd0 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65  F: SQL Trace Eve
25ce0 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  nt Codes.** KEYW
25cf0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41  ORDS: SQLITE_TRA
25d00 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  CE.**.** These c
25d10 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66  onstants identif
25d20 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65  y classes of eve
25d30 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  nts that can be 
25d40 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69  monitored.** usi
25d50 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
25d60 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63  trace_v2()] trac
25d70 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20  ing logic.  The 
25d80 4d 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  M argument.** to
25d90 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
25da0 76 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20  v2(D,M,X,P)] is 
25db0 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61  an OR-ed combina
25dc0 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  tion of one or m
25dd0 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  ore of.** the fo
25de0 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
25df0 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61  s.  ^The first a
25e00 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
25e10 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
25e20 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   is one of the f
25e30 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e  ollowing constan
25e40 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72  ts..**.** New tr
25e50 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  acing constants 
25e60 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
25e70 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
25e80 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
25e90 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75  callback has fou
25ea0 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61  r arguments: xCa
25eb0 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
25ec0 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
25ed0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
25ee0 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63  e integer type c
25ef0 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e  odes above..** ^
25f00 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
25f10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
25f20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
25f30 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
25f40 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d  .** fourth argum
25f50 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
25f60 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  trace_v2()]..** 
25f70 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
25f80 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
25f90 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
25fa0 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
25fb0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
25fc0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
25fd0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
25fe0 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a  ACE_STMT</dt>.**
25ff0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
26000 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62  TRACE_STMT callb
26010 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
26020 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73  hen a prepared s
26030 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73  tatement.** firs
26040 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67  t begins running
26050 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74   and possibly at
26060 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72   other times dur
26070 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75  ing the.** execu
26080 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70  tion of the prep
26090 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20  ared statement, 
260a0 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73  such as at the s
260b0 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  tart of each.** 
260c0 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
260d0 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d  am. ^The P argum
260e0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
260f0 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   to the.** [prep
26100 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
26110 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74   ^The X argument
26120 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
26130 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a   a string which.
26140 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61  ** is the unexpa
26150 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66  nded SQL text of
26160 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
26170 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51  atement or an SQ
26180 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68  L comment .** th
26190 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65  at indicates the
261a0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61   invocation of a
261b0 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20   trigger.  ^The 
261c0 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d  callback can com
261d0 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65  pute.** the same
261e0 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64   text that would
261f0 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72   have been retur
26200 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63  ned by the legac
26210 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  y [sqlite3_trace
26220 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
26230 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20   by using the X 
26240 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20  argument when X 
26250 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22  begins with "--"
26260 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a   and invoking.**
26270 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   [sqlite3_expand
26280 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72  ed_sql(P)] other
26290 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  wise..**.** [[SQ
262a0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
262b0 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  LE]] <dt>SQLITE_
262c0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64  TRACE_PROFILE</d
262d0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
262e0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
262f0 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76  LE callback prov
26300 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65  ides approximate
26310 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69  ly the same.** i
26320 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73  nformation as is
26330 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
26340 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
26350 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  e()] callback..*
26360 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
26370 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
26380 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
26390 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
263a0 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
263b0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d   points to a 64-
263c0 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63  bit integer whic
263d0 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74  h is the estimat
263e0 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d  ed of.** the num
263f0 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  ber of nanosecon
26400 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61  d that the prepa
26410 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  red statement to
26420 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54  ok to run..** ^T
26430 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  he SQLITE_TRACE_
26440 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b  PROFILE callback
26450 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
26460 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
26470 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  inishes..**.** [
26480 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  [SQLITE_TRACE_RO
26490 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  W]] <dt>SQLITE_T
264a0 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a  RACE_ROW</dt>.**
264b0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
264c0 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61  TRACE_ROW callba
264d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
264e0 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65  enever a prepare
264f0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67  d.** statement g
26500 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c  enerates a singl
26510 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e  e row of result.
26520 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67    .** ^The P arg
26530 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
26540 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
26550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
26560 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
26570 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
26580 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
26590 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74  RACE_CLOSE]] <dt
265a0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  >SQLITE_TRACE_CL
265b0 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  OSE</dt>.** <dd>
265c0 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
265d0 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20  _CLOSE callback 
265e0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
265f0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  a database.** co
26600 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
26610 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
26620 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
26630 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
26640 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
26650 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ject.** and the 
26660 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e  X argument is un
26670 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  used..** </dl>.*
26680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
26690 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20  _TRACE_STMT     
266a0 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53    0x01.#define S
266b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
266c0 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66  ILE    0x02.#def
266d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
266e0 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34  _ROW        0x04
266f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26700 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20  TRACE_CLOSE     
26710 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   0x08../*.** CAP
26720 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
26730 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Hook.** METHOD:
26740 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
26750 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
26760 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e  e_v2(D,M,X,P) in
26770 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
26780 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61  s a trace callba
26790 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
267a0 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61   against [databa
267b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
267c0 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79  , using property
267d0 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63   mask M.** and c
267e0 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50  ontext pointer P
267f0 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c  .  ^If the X cal
26800 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c  lback is.** NULL
26810 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73   or if the M mas
26820 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  k is zero, then 
26830 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62  tracing is disab
26840 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61  led.  The.** M a
26850 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
26860 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52  e the bitwise OR
26870 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
26880 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f  of.** zero or mo
26890 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  re [SQLITE_TRACE
268a0 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  ] constants..**.
268b0 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f  ** ^Each call to
268c0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
268d0 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
268e0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76  e3_trace_v2() ov
268f0 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e  errides .** (can
26900 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20  cels) any prior 
26910 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
26920 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69  _trace() or sqli
26930 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a  te3_trace_v2()..
26940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c  **.** ^The X cal
26950 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
26960 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66   whenever any of
26970 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e   the events iden
26980 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61  tified by .** ma
26990 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68  sk M occur.  ^Th
269a0 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e  e integer return
269b0 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20   value from the 
269c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72  callback is curr
269d0 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64  ently.** ignored
269e0 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61  , though this ma
269f0 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  y change in futu
26a00 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61  re releases.  Ca
26a10 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d  llback.** implem
26a20 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
26a30 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20   return zero to 
26a40 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f  ensure future co
26a50 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
26a60 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
26a70 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
26a80 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65  with four argume
26a90 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c  nts: callback(T,
26aa0 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
26ab0 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
26ac0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
26ad0 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74  _TRACE].** const
26ae0 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65  ants to indicate
26af0 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63   why the callbac
26b00 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  k was invoked..*
26b10 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e  * ^The C argumen
26b20 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  t is a copy of t
26b30 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  he context point
26b40 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  er..** The P and
26b50 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
26b60 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
26b70 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
26b80 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  on T..**.** The 
26b90 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
26ba0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
26bb0 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c  intended to repl
26bc0 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  ace the legacy.*
26bd0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
26be0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61  lite3_trace()] a
26bf0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  nd [sqlite3_prof
26c00 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20  ile()], both of 
26c10 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70  which.** are dep
26c20 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20  recated..*/.int 
26c30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
26c40 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
26c50 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a  unsigned uMask,.
26c60 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b    int(*xCallback
26c70 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a  )(unsigned,void*
26c80 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20  ,void*,void*),. 
26c90 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a   void *pCtx.);..
26ca0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26cb0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
26cc0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
26cd0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
26ce0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
26cf0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
26d00 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
26d10 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
26d20 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
26d30 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
26d40 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
26d50 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
26d60 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
26d70 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
26d80 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
26d90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26da0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
26db0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
26dc0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
26dd0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
26de0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
26df0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
26e00 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
26e10 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
26e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
26e30 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
26e40 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
26e50 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
26e60 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
26e70 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
26e80 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
26e90 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
26ea0 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
26eb0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
26ec0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
26ed0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
26ee0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
26ef0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
26f00 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
26f10 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
26f20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
26f30 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
26f40 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
26f50 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
26f60 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
26f70 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
26f80 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
26f90 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
26fa0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
26fb0 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
26fc0 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
26fd0 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
26fe0 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
26ff0 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
27000 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
27010 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
27020 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
27030 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
27040 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
27050 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
27060 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
27070 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
27080 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
27090 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
270a0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
270b0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
270c0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
270d0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
270e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
270f0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
27100 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
27110 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
27120 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
27130 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
27140 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
27150 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
27160 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
27170 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
27180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27190 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
271a0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
271b0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
271c0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
271d0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
271e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
271f0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
27200 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
27210 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
27220 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
27230 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
27240 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
27250 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
27260 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
27270 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
27280 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
27290 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
272a0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
272b0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
272c0 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
272d0 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
272e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
272f0 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
27300 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
27310 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
27320 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
27330 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
27340 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
27350 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
27360 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
27370 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
27380 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
27390 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
273a0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
273b0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
273c0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
273d0 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
273e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
273f0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
27400 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
27410 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
27420 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
27430 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
27440 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
27450 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
27460 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
27470 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
27480 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
27490 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
274a0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
274b0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
274c0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
274d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
274e0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
274f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
27500 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
27510 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
27520 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
27530 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
27540 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
27550 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
27560 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
27570 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
27580 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
27590 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
275a0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
275b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
275c0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
275d0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
275e0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
275f0 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
27600 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
27610 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
27620 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
27630 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
27640 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
27650 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
27660 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
27670 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
27680 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
27690 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
276a0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
276b0 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
276c0 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
276d0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
276e0 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
276f0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
27700 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
27710 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
27720 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
27730 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
27740 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
27750 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
27760 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
27770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
27780 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
27790 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
277a0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
277b0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
277c0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
277d0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
277e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
277f0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
27800 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
27810 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
27820 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
27830 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
27840 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
27850 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
27860 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
27870 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
27880 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
27890 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
278a0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
278b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
278c0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
278d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
278e0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
278f0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
27900 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
27910 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
27920 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
27930 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
27940 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
27950 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
27960 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
27970 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
27980 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
27990 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
279a0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
279b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
279c0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
279d0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
279e0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
279f0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
27a00 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
27a10 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
27a20 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
27a30 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
27a40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
27a50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
27a60 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
27a70 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
27a80 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
27a90 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
27aa0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
27ab0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
27ac0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
27ad0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
27ae0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
27af0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
27b00 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
27b10 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
27b20 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
27b30 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
27b40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
27b50 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
27b60 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
27b70 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
27b80 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
27b90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27ba0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
27bb0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
27bc0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
27bd0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
27be0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
27bf0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
27c00 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
27c10 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
27c20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
27c30 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
27c40 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
27c50 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
27c60 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
27c70 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
27c80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27c90 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
27ca0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
27cb0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
27cc0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
27cd0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
27ce0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
27cf0 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
27d00 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
27d10 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
27d20 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
27d30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
27d40 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
27d50 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
27d60 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
27d70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
27d80 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
27d90 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
27da0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
27db0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
27dc0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
27dd0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
27de0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
27df0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
27e00 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
27e10 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
27e20 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
27e30 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
27e40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
27e50 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
27e60 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
27e70 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
27e80 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
27e90 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
27ea0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
27eb0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
27ec0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
27ed0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
27ee0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
27ef0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
27f00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
27f10 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
27f20 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
27f30 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
27f40 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
27f50 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
27f60 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
27f70 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
27f80 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
27f90 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
27fa0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
27fb0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
27fc0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
27fd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27fe0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
27ff0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
28000 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
28010 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
28020 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
28030 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
28040 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
28050 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
28060 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
28070 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
28080 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
28090 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
280a0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
280b0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
280c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
280d0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
280e0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
280f0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
28100 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
28110 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
28120 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
28130 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
28140 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
28150 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
28160 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
28170 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
28180 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
28190 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
281a0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
281b0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
281c0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
281d0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
281e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
281f0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
28200 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
28210 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
28220 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
28230 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
28240 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
28250 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
28260 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
28270 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
28280 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
28290 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
282a0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
282b0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
282c0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
282d0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
282e0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
282f0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
28300 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
28310 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
28320 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
28330 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
28340 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
28350 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
28360 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
28370 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
28380 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
28390 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
283a0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
283b0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
283c0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
283d0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
283e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
283f0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
28400 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
28410 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
28420 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
28430 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
28440 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
28450 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
28460 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
28470 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
28480 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
28490 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
284a0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
284b0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
284c0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
284d0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
284e0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
284f0 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
28500 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
28510 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
28520 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
28530 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
28540 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
28550 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
28560 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
28570 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
28580 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
28590 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
285a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
285b0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
285c0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
285d0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
285e0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20   option..** URI 
285f0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
28600 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
28610 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
28620 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
28630 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
28640 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
28650 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
28660 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
28670 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
28680 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
28690 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
286a0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
286b0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
286c0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
286d0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
286e0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
286f0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
28700 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
28710 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
28720 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
28730 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
28740 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
28750 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
28760 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
28770 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
28780 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
28790 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
287a0 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
287b0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
287c0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
287d0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
287e0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
287f0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
28800 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
28810 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
28820 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
28830 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
28840 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
28850 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
28860 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
28870 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
28880 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
28890 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
288a0 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
288b0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
288c0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
288d0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
288e0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
288f0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
28900 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
28910 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
28920 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
28930 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
28940 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
28950 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77  path. .** ^(On w
28960 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
28970 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
28980 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
28990 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
289a0 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
289b0 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a  g. "C:").)^.**.*
289c0 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
289d0 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
289e0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
289f0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
28a00 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
28a10 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
28a20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
28a30 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
28a40 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
28a50 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
28a60 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
28a70 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  ]..** SQLite and
28a80 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56   its built-in [V
28a90 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20  FSes] interpret 
28aa0 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
28ab0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28ac0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
28ad0 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
28ae0 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
28af0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
28b00 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
28b10 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
28b20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
28b30 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
28b40 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
28b50 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
28b60 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
28b70 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
28b80 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
28b90 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
28ba0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
28bb0 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
28bc0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
28bd0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
28be0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
28bf0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
28c00 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
28c10 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
28c20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
28c30 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
28c40 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
28c50 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
28c60 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
28c70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
28c80 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
28c90 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
28ca0 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
28cb0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
28cc0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
28cd0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
28ce0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
28cf0 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
28d00 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
28d10 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
28d20 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
28d30 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20  ,.**     "rwc", 
28d40 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74  or "memory". Att
28d50 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
28d60 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
28d70 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61  alue is.**     a
28d80 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
28d90 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
28da0 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
28db0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
28dc0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
28dd0 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
28de0 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
28df0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
28e00 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
28e10 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
28e20 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
28e30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
28e40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
28e50 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
28e60 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
28e70 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
28e80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
28e90 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
28ea0 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
28eb0 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
28ec0 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
28ed0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
28ee0 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
28ef0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
28f00 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
28f10 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
28f20 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
28f30 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
28f40 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
28f50 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
28f60 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
28f70 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65  CREATE.  ^If the
28f80 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a   mode option is.
28f90 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d  **     set to "m
28fa0 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75  emory" then a pu
28fb0 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  re [in-memory da
28fc0 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76  tabase] that nev
28fd0 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20  er reads.**     
28fe0 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64  or writes from d
28ff0 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74  isk is used. ^It
29000 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
29010 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
29020 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d  for.**     the m
29030 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
29040 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72  at is less restr
29050 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
29060 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
29070 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70       the flags p
29080 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69  assed in the thi
29090 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
290a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
290b0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
290c0 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
290d0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
290e0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
290f0 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
29100 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
29110 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
29120 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
29130 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
29140 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
29150 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
29160 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
29170 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
29180 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
29190 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
291a0 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
291b0 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
291c0 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
291d0 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
291e0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
291f0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
29200 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
29210 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
29220 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
29230 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
29240 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
29250 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
29260 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
29270 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
29280 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
29290 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73   behavior reques
292a0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
292b0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
292c0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
292d0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
292e0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
292f0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70  **.**  <li> <b>p
29300 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73  sow</b>: ^The ps
29310 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64  ow parameter ind
29320 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f  icates whether o
29330 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20  r not the.**    
29340 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
29350 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
29360 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
29370 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
29380 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
29390 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
293a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
293b0 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  sides..**.**  <l
293c0 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e  i> <b>nolock</b>
293d0 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61  : ^The nolock pa
293e0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
293f0 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d  lean query param
29400 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63  eter.**     whic
29410 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65  h if set disable
29420 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69  s file locking i
29430 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  n rollback journ
29440 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a  al modes.  This.
29450 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c  **     is useful
29460 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61   for accessing a
29470 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66   database on a f
29480 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64  ilesystem that d
29490 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73  oes not.**     s
294a0 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20  upport locking. 
294b0 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62   Caution:  Datab
294c0 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d  ase corruption m
294d0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74  ight result if t
294e0 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72  wo.**     or mor
294f0 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74  e processes writ
29500 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  e to the same da
29510 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f  tabase and any o
29520 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20  ne of those.**  
29530 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65     processes use
29540 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a  s nolock=1..**.*
29550 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74  *  <li> <b>immut
29560 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69  able</b>: ^The i
29570 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74  mmutable paramet
29580 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
29590 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
295a0 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69  ameter that indi
295b0 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64  cates that the d
295c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
295d0 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  stored on.**    
295e0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
295f0 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62  .  ^When immutab
29600 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74  le is set, SQLit
29610 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
29620 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61  he.**     databa
29630 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62  se file cannot b
29640 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  e changed, even 
29650 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74  by a process wit
29660 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20  h higher.**     
29670 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73  privilege, and s
29680 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  o the database i
29690 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e  s opened read-on
296a0 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69  ly and all locki
296b0 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68  ng.**     and ch
296c0 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69  ange detection i
296d0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75  s disabled.  Cau
296e0 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68  tion: Setting th
296f0 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20  e immutable.**  
29700 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61     property on a
29710 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
29720 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74  hat does in fact
29730 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75   change can resu
29740 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63  lt.**     in inc
29750 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73  orrect query res
29760 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ults and/or [SQL
29770 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72  ITE_CORRUPT] err
29780 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20  ors..**     See 
29790 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
297a0 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a  CAP_IMMUTABLE]..
297b0 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75  **       .** </u
297c0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
297d0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
297e0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
297f0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
29800 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
29810 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
29820 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
29830 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
29840 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
29850 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
29860 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
29870 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
29880 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
29890 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
298a0 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
298b0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
298c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
298d0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
298e0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
298f0 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
29900 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
29910 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
29920 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
29930 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
29940 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
29950 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
29960 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
29970 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
29980 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
29990 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
299a0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
299b0 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
299c0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
299d0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
299e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
299f0 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
29a00 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
29a10 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
29a20 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
29a30 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
29a40 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
29a50 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
29a60 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
29a70 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
29a80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
29a90 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
29aa0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
29ab0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
29ac0 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
29ad0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
29ae0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
29af0 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
29b00 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
29b10 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
29b20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
29b30 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
29b40 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
29b50 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
29b60 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
29b70 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
29b80 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
29b90 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
29ba0 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
29bb0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
29bc0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
29bd0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
29be0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
29bf0 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
29c00 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
29c10 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
29c20 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
29c30 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
29c40 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
29c50 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
29c60 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
29c70 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
29c80 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
29c90 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
29ca0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
29cb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
29cc0 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
29cd0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
29ce0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
29cf0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
29d00 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
29d10 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
29d20 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
29d30 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
29d40 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
29d50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
29d60 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
29d70 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74  .db?vfs=unix-dot
29d80 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  file <td>.**    
29d90 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
29da0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
29db0 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
29dc0 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
29dd0 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20  dotfile".**     
29de0 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64       that uses d
29df0 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63  ot-files in plac
29e00 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73  e of posix advis
29e10 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20  ory locking..** 
29e20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
29e30 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
29e40 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
29e50 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
29e60 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
29e70 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
29e80 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
29e90 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
29ea0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
29eb0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
29ec0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
29ed0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
29ee0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
29ef0 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
29f00 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
29f10 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
29f20 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
29f30 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
29f40 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
29f50 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
29f60 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
29f70 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
29f80 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
29f90 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
29fa0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
29fb0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
29fc0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
29fd0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
29fe0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
29ff0 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
2a000 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
2a010 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
2a020 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
2a030 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
2a040 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
2a050 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
2a060 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
2a070 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
2a080 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
2a090 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
2a0a0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
2a0b0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2a0c0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
2a0d0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
2a0e0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
2a0f0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
2a100 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
2a110 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
2a120 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
2a130 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
2a140 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
2a150 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
2a160 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
2a170 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
2a180 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
2a190 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
2a1a0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
2a1b0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
2a1c0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
2a1d0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
2a1e0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
2a1f0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
2a200 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2a210 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
2a220 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
2a230 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
2a240 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
2a250 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
2a260 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
2a270 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
2a280 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
2a290 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
2a2a0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
2a2b0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
2a2c0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
2a2d0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
2a2e0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
2a2f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2a300 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
2a310 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71  ctory].*/.int sq
2a320 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
2a330 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
2a340 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
2a350 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
2a360 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
2a370 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
2a380 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
2a390 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
2a3a0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
2a3b0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
2a3c0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
2a3d0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
2a3e0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
2a3f0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
2a400 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
2a410 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
2a420 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2a430 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
2a440 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
2a450 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
2a460 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
2a470 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
2a480 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
2a490 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
2a4a0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
2a4b0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
2a4c0 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
2a4d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2a4e0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
2a4f0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
2a500 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
2a510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a520 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
2a530 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
2a540 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
2a550 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
2a560 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
2a570 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2a580 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
2a590 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
2a5a0 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
2a5b0 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
2a5c0 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
2a5d0 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
2a5e0 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
2a5f0 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
2a600 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
2a610 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
2a620 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
2a630 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
2a640 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
2a650 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
2a660 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
2a670 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2a680 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
2a690 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
2a6a0 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
2a6b0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
2a6c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
2a6d0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
2a6e0 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
2a6f0 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
2a700 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
2a710 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
2a720 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
2a730 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
2a740 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
2a750 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
2a760 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
2a770 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
2a780 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
2a790 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
2a7a0 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
2a7b0 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
2a7c0 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
2a7d0 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
2a7e0 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
2a7f0 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
2a800 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
2a810 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
2a820 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
2a830 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
2a840 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2a850 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
2a860 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
2a870 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
2a880 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
2a890 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
2a8a0 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
2a8b0 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
2a8c0 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
2a8d0 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
2a8e0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
2a8f0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
2a900 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
2a910 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
2a920 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
2a930 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
2a940 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
2a950 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
2a960 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
2a970 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
2a980 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
2a990 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
2a9a0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
2a9b0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
2a9c0 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
2a9d0 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
2a9e0 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
2a9f0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
2aa00 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
2aa10 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
2aa20 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
2aa30 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
2aa40 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
2aa50 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
2aa60 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
2aa70 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
2aa80 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
2aa90 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
2aaa0 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
2aab0 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
2aac0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
2aad0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
2aae0 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
2aaf0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
2ab00 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
2ab10 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
2ab20 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
2ab30 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
2ab40 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
2ab50 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
2ab60 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
2ab70 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
2ab80 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
2ab90 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
2aba0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
2abb0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
2abc0 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
2abd0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
2abe0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2abf0 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
2ac00 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
2ac10 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
2ac20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
2ac30 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
2ac40 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
2ac50 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
2ac60 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
2ac70 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
2ac80 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
2ac90 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
2aca0 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
2acb0 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
2acc0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
2acd0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
2ace0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
2acf0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2ad00 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
2ad10 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ble..**.** See t
2ad20 68 65 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  he [URI filename
2ad30 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2ad40 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2ad50 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 63  nformation..*/.c
2ad60 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2ad70 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
2ad80 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
2ad90 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
2ada0 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
2adb0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
2adc0 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
2add0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
2ade0 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
2adf0 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
2ae00 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2ae10 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
2ae20 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
2ae30 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
2ae40 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
2ae50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
2ae60 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
2ae70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ae80 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
2ae90 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
2aea0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
2aeb0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2aec0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2aed0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
2aee0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
2aef0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
2af00 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
2af10 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
2af20 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
2af30 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
2af40 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
2af50 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
2af60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2af70 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
2af80 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
2af90 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
2afa0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
2afb0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
2afc0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2afd0 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
2afe0 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
2aff0 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
2b000 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  isabled..**.** T
2b010 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2b020 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 72  ed by sqlite3_er
2b030 72 63 6f 64 65 28 29 20 61 6e 64 2f 6f 72 0a 2a  rcode() and/or.*
2b040 2a 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  * sqlite3_extend
2b050 65 64 5f 65 72 72 63 6f 64 65 28 29 20 6d 69 67  ed_errcode() mig
2b060 68 74 20 63 68 61 6e 67 65 20 77 69 74 68 20 65  ht change with e
2b070 61 63 68 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a  ach API call..**
2b080 20 45 78 63 65 70 74 2c 20 74 68 65 72 65 20 61   Except, there a
2b090 72 65 20 73 6f 6d 65 20 69 6e 74 65 72 66 61 63  re some interfac
2b0a0 65 73 20 74 68 61 74 20 61 72 65 20 67 75 61 72  es that are guar
2b0b0 61 6e 74 65 65 64 20 74 6f 20 6e 65 76 65 72 0a  anteed to never.
2b0c0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ** change the va
2b0d0 6c 75 65 20 6f 66 20 74 68 65 20 65 72 72 6f 72  lue of the error
2b0e0 20 63 6f 64 65 2e 20 20 54 68 65 20 65 72 72 6f   code.  The erro
2b0f0 72 2d 63 6f 64 65 20 70 72 65 73 65 72 76 69 6e  r-code preservin
2b100 67 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  g.** interfaces 
2b110 61 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  are:.**.** <ul>.
2b120 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
2b130 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69  errcode().** <li
2b140 3e 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  > sqlite3_extend
2b150 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
2b160 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72  <li> sqlite3_err
2b170 6d 73 67 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71  msg().** <li> sq
2b180 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
2b190 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2b1a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
2b1b0 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
2b1c0 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
2b1d0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
2b1e0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
2b1f0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
2b200 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
2b210 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2b220 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2b230 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
2b240 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
2b250 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
2b260 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
2b270 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
2b280 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
2b290 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
2b2a0 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
2b2b0 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
2b2c0 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
2b2d0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
2b2e0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
2b2f0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
2b300 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2b310 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
2b320 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
2b330 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
2b340 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
2b350 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b360 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
2b370 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
2b380 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
2b390 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
2b3a0 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
2b3b0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
2b3c0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2b3d0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
2b3e0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
2b3f0 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
2b400 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
2b410 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
2b420 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
2b430 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
2b440 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
2b450 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
2b460 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
2b470 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
2b480 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
2b490 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
2b4a0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
2b4b0 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
2b4c0 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
2b4d0 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
2b4e0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
2b4f0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
2b500 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
2b510 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
2b520 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
2b530 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
2b540 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
2b550 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
2b560 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
2b570 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
2b580 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
2b590 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
2b5a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b5b0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
2b5c0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
2b5d0 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
2b5e0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
2b5f0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
2b600 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
2b610 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
2b620 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
2b630 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
2b640 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
2b650 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
2b660 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
2b670 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
2b680 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
2b690 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
2b6a0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
2b6b0 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
2b6c0 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
2b6d0 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
2b6e0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
2b6f0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2b700 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
2b710 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
2b720 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
2b730 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
2b740 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
2b750 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
2b760 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
2b770 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
2b780 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
2b790 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
2b7a0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
2b7b0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
2b7c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2b7d0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
2b7e0 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  3*);.const char 
2b7f0 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
2b800 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2b810 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20  I3REF: Prepared 
2b820 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2b830 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
2b840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b850 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
2b860 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
2b870 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
2b880 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
2b890 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
2b8a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
2b8b0 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  .** has been com
2b8c0 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72  piled into binar
2b8d0 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65  y form and is re
2b8e0 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61  ady to be evalua
2b8f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b  ted..**.** Think
2b900 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61   of each SQL sta
2b910 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61  tement as a sepa
2b920 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72  rate computer pr
2b930 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f  ogram.  The.** o
2b940 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
2b950 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e   is source code.
2b960 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61    A prepared sta
2b970 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a  tement object .*
2b980 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65  * is the compile
2b990 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20  d object code.  
2b9a0 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20  All SQL must be 
2b9b0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
2b9c0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2b9d0 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74  tement before it
2b9e0 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a   can be run..**.
2b9f0 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c  ** The life-cycl
2ba00 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20  e of a prepared 
2ba10 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
2ba20 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69   usually goes li
2ba30 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
2ba40 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
2ba50 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20  te the prepared 
2ba60 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
2ba70 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2ba80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a  prepare_v2()]..*
2ba90 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
2baa0 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  es to [parameter
2bab0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
2bac0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
2bad0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
2bae0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
2baf0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
2bb00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2bb10 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
2bb20 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
2bb30 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
2bb40 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2bb50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2bb60 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
2bb70 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
2bb80 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
2bb90 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
2bba0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
2bbb0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
2bbc0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2bbd0 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
2bbe0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2bbf0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
2bc00 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
2bc10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
2bc20 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20  -time Limits.** 
2bc30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
2bc40 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
2bc50 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
2bc60 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
2bc70 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
2bc80 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
2bc90 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
2bca0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
2bcb0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
2bcc0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2bcd0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
2bce0 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
2bcf0 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
2bd00 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
2bd10 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
2bd20 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
2bd30 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
2bd40 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
2bd50 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
2bd60 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
2bd70 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
2bd80 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
2bd90 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
2bda0 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
2bdb0 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
2bdc0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
2bdd0 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
2bde0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
2bdf0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
2be00 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
2be10 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
2be20 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
2be30 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
2be40 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
2be50 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
2be60 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
2be70 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
2be80 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
2be90 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
2bea0 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
2beb0 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
2bec0 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
2bed0 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
2bee0 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
2bef0 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
2bf00 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
2bf10 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
2bf20 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
2bf30 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
2bf40 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
2bf50 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
2bf60 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
2bf70 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
2bf80 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
2bf90 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
2bfa0 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
2bfb0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
2bfc0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2bfd0 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
2bfe0 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
2bff0 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
2c000 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
2c010 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
2c020 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
2c030 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
2c040 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
2c050 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
2c060 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
2c070 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
2c080 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
2c090 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
2c0a0 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
2c0b0 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
2c0c0 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
2c0d0 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
2c0e0 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
2c0f0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
2c100 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
2c110 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
2c120 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
2c130 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
2c140 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
2c150 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
2c160 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
2c170 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
2c180 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
2c190 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
2c1a0 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
2c1b0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
2c1c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
2c1d0 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
2c1e0 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
2c1f0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
2c200 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
2c210 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
2c220 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
2c230 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
2c240 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
2c250 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
2c260 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
2c270 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
2c280 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
2c290 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
2c2a0 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
2c2b0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
2c2c0 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
2c2d0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
2c2e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
2c2f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
2c300 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
2c310 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
2c320 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
2c330 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
2c340 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
2c350 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
2c360 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
2c370 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
2c380 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
2c390 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
2c3a0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
2c3b0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
2c3c0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
2c3d0 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
2c3e0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
2c3f0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
2c400 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
2c410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2c420 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
2c430 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
2c440 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
2c450 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
2c460 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
2c470 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2c480 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
2c490 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
2c4a0 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
2c4b0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
2c4c0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
2c4d0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
2c4e0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
2c4f0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
2c500 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
2c510 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
2c520 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
2c530 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
2c540 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
2c550 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
2c560 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
2c570 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
2c580 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2c590 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2c5a0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
2c5b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2c5c0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
2c5d0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
2c5e0 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
2c5f0 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
2c600 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2c610 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
2c620 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2c630 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
2c640 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2c650 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
2c660 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
2c670 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
2c680 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2c690 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
2c6a0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2c6b0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
2c6c0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2c6d0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
2c6e0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
2c6f0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
2c700 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
2c710 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2c720 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
2c730 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2c740 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
2c750 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
2c760 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
2c770 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
2c780 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2c790 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
2c7a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2c7b0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
2c7c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2c7d0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
2c7e0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
2c7f0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
2c800 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2c810 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2c820 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
2c830 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2c840 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2c850 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2c860 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2c870 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
2c880 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
2c890 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
2c8a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2c8b0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
2c8c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2c8d0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
2c8e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2c8f0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
2c900 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
2c910 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
2c920 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
2c930 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
2c940 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  L statement.  If
2c950 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c960 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68  e_v2()] or.** th
2c970 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69  e equivalent tri
2c980 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73  es to allocate s
2c990 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68  pace for more th
2c9a0 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63  an this many opc
2c9b0 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e  odes.** in a sin
2c9c0 67 6c 65 20 70 72 65 70 61 72 65 64 20 73 74 61  gle prepared sta
2c9d0 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54  tement, an SQLIT
2c9e0 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73  E_NOMEM error is
2c9f0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
2ca00 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2ca10 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2ca20 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
2ca30 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2ca40 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
2ca50 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2ca60 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2ca70 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
2ca80 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2ca90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2caa0 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
2cab0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
2cac0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
2cad0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2cae0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
2caf0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2cb00 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
2cb10 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2cb20 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2cb30 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
2cb40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2cb50 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2cb60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2cb70 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
2cb80 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
2cb90 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
2cba0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
2cbb0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
2cbc0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2cbd0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2cbe0 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
2cbf0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2cc00 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2cc10 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
2cc20 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
2cc30 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
2cc40 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
2cc50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
2cc60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2cc70 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2cc80 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
2cc90 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2cca0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
2ccb0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
2ccc0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
2ccd0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
2cce0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2ccf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2cd00 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c  ER_THREADS]] ^(<
2cd10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2cd20 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f  WORKER_THREADS</
2cd30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2cd40 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2cd50 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65   auxiliary worke
2cd60 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61  r threads that a
2cd70 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70   single.** [prep
2cd80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cd90 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29  may start.</dd>)
2cda0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
2cdb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2cdc0 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
2cdd0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
2cde0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2cdf0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
2ce00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
2ce10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2ce20 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
2ce30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
2ce40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ce50 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
2ce60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ce70 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
2ce80 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
2ce90 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
2cea0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2ceb0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
2cec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ced0 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
2cee0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2cef0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
2cf00 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
2cf10 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
2cf20 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
2cf30 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
2cf40 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
2cf50 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
2cf60 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
2cf70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2cf80 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
2cf90 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
2cfa0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
2cfb0 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
2cfc0 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
2cfd0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f   SQLITE_LIMIT_WO
2cfe0 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20  RKER_THREADS    
2cff0 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a         11../*.**
2d000 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61   CAPI3REF: Prepa
2d010 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54  re Flags.**.** T
2d020 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
2d030 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c  efine various fl
2d040 61 67 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ags that can be 
2d050 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22  passed into.** "
2d060 70 72 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d  prepFlags" param
2d070 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c  eter of the [sql
2d080 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2d090 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
2d0a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2d0b0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  )] interfaces..*
2d0c0 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d  *.** New flags m
2d0d0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
2d0e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
2d0f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
2d100 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
2d110 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2d120 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ENT]] ^(<dt>SQLI
2d130 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2d140 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  STENT</dt>.** <d
2d150 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45  d>The SQLITE_PRE
2d160 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20  PARE_PERSISTENT 
2d170 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74 20 74  flag is a hint t
2d180 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e  o the query plan
2d190 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ner.** that the 
2d1a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d1b0 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69  nt will be retai
2d1c0 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74  ned for a long t
2d1d0 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61  ime and.** proba
2d1e0 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20  bly reused many 
2d1f0 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75  times.)^ ^Withou
2d200 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71  t this flag, [sq
2d210 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2d220 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2d230 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2d240 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20  ()] assume that 
2d250 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2d260 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20  tement will .** 
2d270 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63  be used just onc
2d280 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66  e or at most a f
2d290 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65  ew times and the
2d2a0 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e  n destroyed usin
2d2b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  g.** [sqlite3_fi
2d2c0 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69  nalize()] relati
2d2d0 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63  vely soon. The c
2d2e0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
2d2f0 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e  ation acts.** on
2d300 20 74 68 69 73 20 68 69 6e 74 20 62 79 20 61 76   this hint by av
2d310 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f  oiding the use o
2d320 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  f [lookaside mem
2d330 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74  ory] so as not t
2d340 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65  o.** deplete the
2d350 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f   limited store o
2d360 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
2d370 72 79 2e 20 46 75 74 75 72 65 20 76 65 72 73 69  ry. Future versi
2d380 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ons of.** SQLite
2d390 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73   may act on this
2d3a0 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c   hint differentl
2d3b0 79 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  y..**.** [[SQLIT
2d3c0 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c  E_PREPARE_NORMAL
2d3d0 49 5a 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IZE]] <dt>SQLITE
2d3e0 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49  _PREPARE_NORMALI
2d3f0 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ZE</dt>.** <dd>T
2d400 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  he SQLITE_PREPAR
2d410 45 5f 4e 4f 52 4d 41 4c 49 5a 45 20 66 6c 61 67  E_NORMALIZE flag
2d420 20 69 73 20 61 20 6e 6f 2d 6f 70 2e 20 54 68 69   is a no-op. Thi
2d430 73 20 66 6c 61 67 20 75 73 65 64 0a 2a 2a 20 74  s flag used.** t
2d440 6f 20 62 65 20 72 65 71 75 69 72 65 64 20 66 6f  o be required fo
2d450 72 20 61 6e 79 20 70 72 65 70 61 72 65 64 20 73  r any prepared s
2d460 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 77 61  tatement that wa
2d470 6e 74 65 64 20 74 6f 20 75 73 65 20 74 68 65 0a  nted to use the.
2d480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 6f 72 6d  ** [sqlite3_norm
2d490 61 6c 69 7a 65 64 5f 73 71 6c 28 29 5d 20 69 6e  alized_sql()] in
2d4a0 74 65 72 66 61 63 65 2e 20 20 48 6f 77 65 76 65  terface.  Howeve
2d4b0 72 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  r, the.** [sqlit
2d4c0 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71  e3_normalized_sq
2d4d0 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  l()] interface i
2d4e0 73 20 6e 6f 77 20 61 76 61 69 6c 61 62 6c 65 20  s now available 
2d4f0 74 6f 20 61 6c 6c 0a 2a 2a 20 70 72 65 70 61 72  to all.** prepar
2d500 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 72  ed statements, r
2d510 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
2d520 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 79  ther or not they
2d530 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 66 6c 61   use this.** fla
2d540 67 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  g..**.** [[SQLIT
2d550 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41  E_PREPARE_NO_VTA
2d560 42 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 50  B]] <dt>SQLITE_P
2d570 52 45 50 41 52 45 5f 4e 4f 5f 56 54 41 42 3c 2f  REPARE_NO_VTAB</
2d580 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53  dt>.** <dd>The S
2d590 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2d5a0 5f 56 54 41 42 20 66 6c 61 67 20 63 61 75 73 65  _VTAB flag cause
2d5b0 73 20 74 68 65 20 53 51 4c 20 63 6f 6d 70 69 6c  s the SQL compil
2d5c0 65 72 0a 2a 2a 20 74 6f 20 72 65 74 75 72 6e 20  er.** to return 
2d5d0 61 6e 20 65 72 72 6f 72 20 28 65 72 72 6f 72 20  an error (error 
2d5e0 63 6f 64 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  code SQLITE_ERRO
2d5f0 52 29 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  R) if the statem
2d600 65 6e 74 20 75 73 65 73 0a 2a 2a 20 61 6e 79 20  ent uses.** any 
2d610 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a  virtual tables..
2d620 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
2d630 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ine SQLITE_PREPA
2d640 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20 20  RE_PERSISTENT   
2d650 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31 0a             0x01.
2d660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
2d670 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45  REPARE_NORMALIZE
2d680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
2d690 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x02.#define SQLI
2d6a0 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56 54  TE_PREPARE_NO_VT
2d6b0 41 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AB              
2d6c0 20 20 20 30 78 30 34 0a 0a 2f 2a 0a 2a 2a 20 43     0x04../*.** C
2d6d0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
2d6e0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
2d6f0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
2d700 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
2d710 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54  compiler}.** MET
2d720 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20  HOD: sqlite3.** 
2d730 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
2d740 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2d750 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
2d760 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20  L statement, it 
2d770 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
2d780 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
2d790 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
2d7a0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
2d7b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20  these routines. 
2d7c0 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f   Or, in other wo
2d7d0 72 64 73 2c 20 74 68 65 73 65 20 72 6f 75 74 69  rds, these routi
2d7e0 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74  nes.** are const
2d7f0 72 75 63 74 6f 72 73 20 66 6f 72 20 74 68 65 20  ructors for the 
2d800 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d810 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ent] object..**.
2d820 2a 2a 20 54 68 65 20 70 72 65 66 65 72 72 65 64  ** The preferred
2d830 20 72 6f 75 74 69 6e 65 20 74 6f 20 75 73 65 20   routine to use 
2d840 69 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  is [sqlite3_prep
2d850 61 72 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a  are_v2()].  The.
2d860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2d870 61 72 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  are()] interface
2d880 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 73   is legacy and s
2d890 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64  hould be avoided
2d8a0 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ..** [sqlite3_pr
2d8b0 65 70 61 72 65 5f 76 33 28 29 5d 20 68 61 73 20  epare_v3()] has 
2d8c0 61 6e 20 65 78 74 72 61 20 22 70 72 65 70 46 6c  an extra "prepFl
2d8d0 61 67 73 22 20 6f 70 74 69 6f 6e 20 74 68 61 74  ags" option that
2d8e0 20 69 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20   is used.** for 
2d8f0 73 70 65 63 69 61 6c 20 70 75 72 70 6f 73 65 73  special purposes
2d900 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20  ..**.** The use 
2d910 6f 66 20 74 68 65 20 55 54 46 2d 38 20 69 6e 74  of the UTF-8 int
2d920 65 72 66 61 63 65 73 20 69 73 20 70 72 65 66 65  erfaces is prefe
2d930 72 72 65 64 2c 20 61 73 20 53 51 4c 69 74 65 20  rred, as SQLite 
2d940 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65  currently.** doe
2d950 73 20 61 6c 6c 20 70 61 72 73 69 6e 67 20 75 73  s all parsing us
2d960 69 6e 67 20 55 54 46 2d 38 2e 20 20 54 68 65 20  ing UTF-8.  The 
2d970 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65  UTF-16 interface
2d980 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
2d990 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e  * as a convenien
2d9a0 63 65 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20  ce.  The UTF-16 
2d9b0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 20  interfaces work 
2d9c0 62 79 20 63 6f 6e 76 65 72 74 69 6e 67 20 74 68  by converting th
2d9d0 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65 78 74 20  e.** input text 
2d9e0 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e  into UTF-8, then
2d9f0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f   invoking the co
2da00 72 72 65 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d  rresponding UTF-
2da10 38 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  8 interface..**.
2da20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
2da30 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
2da40 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2da50 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
2da60 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
2da70 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2da80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
2da90 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2daa0 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
2dab0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2dac0 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
2dad0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2dae0 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
2daf0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
2db00 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2db10 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
2db20 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
2db30 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
2db40 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
2db50 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2db60 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
2db70 72 65 70 61 72 65 28 29 2c 20 73 71 6c 69 74 65  repare(), sqlite
2db80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c 0a  3_prepare_v2(),.
2db90 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  ** and sqlite3_p
2dba0 72 65 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69  repare_v3().** i
2dbb0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
2dbc0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
2dbd0 5f 70 72 65 70 61 72 65 31 36 28 29 2c 20 73 71  _prepare16(), sq
2dbe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2dbf0 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c  v2(),.** and sql
2dc00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2dc10 33 28 29 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  3() use UTF-16..
2dc20 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
2dc30 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
2dc40 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a  negative, then z
2dc50 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
2dc60 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
2dc70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
2dc80 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73  ^If nByte is pos
2dc90 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  itive, then it i
2dca0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2dcb0 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72  of bytes read fr
2dcc0 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42  om zSql.  ^If nB
2dcd0 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  yte is zero, the
2dce0 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a  n no prepared.**
2dcf0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65   statement is ge
2dd00 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74  nerated..** If t
2dd10 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20  he caller knows 
2dd20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
2dd30 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
2dd40 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
2dd50 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73  .** there is a s
2dd60 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65  mall performance
2dd70 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61   advantage to pa
2dd80 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
2dd90 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
2dda0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2ddb0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
2ddc0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
2ddd0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
2dde0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
2ddf0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  or..**.** ^If pz
2de00 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
2de10 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
2de20 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2de30 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
2de40 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
2de50 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
2de60 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
2de70 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
2de80 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
2de90 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
2dea0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2deb0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
2dec0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2ded0 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
2dee0 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
2def0 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
2df00 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
2df10 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
2df20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2df30 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
2df40 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
2df50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
2df60 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
2df70 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
2df80 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
2df90 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
2dfa0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
2dfb0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
2dfc0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
2dfd0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
2dfe0 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
2dff0 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
2e000 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
2e010 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
2e020 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
2e030 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
2e040 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
2e050 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
2e060 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e070 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
2e080 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2e090 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
2e0a0 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
2e0b0 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
2e0c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
2e0d0 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
2e0e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2e0f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
2e100 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
2e110 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2e120 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
2e130 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2e140 65 5f 76 32 28 29 2c 20 73 71 6c 69 74 65 33 5f  e_v2(), sqlite3_
2e150 70 72 65 70 61 72 65 5f 76 33 28 29 2c 20 73 71  prepare_v3(), sq
2e160 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2e170 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c  v2(),.** and sql
2e180 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2e190 33 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  3() interfaces a
2e1a0 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  re recommended f
2e1b0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
2e1c0 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65  ams..** The olde
2e1d0 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 71  r interfaces (sq
2e1e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2e1f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2e200 61 72 65 31 36 28 29 29 0a 2a 2a 20 61 72 65 20  are16()).** are 
2e210 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
2e220 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2e230 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
2e240 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
2e250 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
2e260 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  vX" interfaces, 
2e270 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2e280 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
2e290 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
2e2a0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2e2b0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
2e2c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2e2d0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
2e2e0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
2e2f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2e300 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
2e310 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
2e320 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
2e330 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
2e340 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
2e350 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2e360 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
2e370 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
2e380 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
2e390 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
2e3a0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
2e3b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e3c0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2e3d0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
2e3e0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2e3f0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
2e400 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
2e410 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
2e420 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
2e430 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
2e440 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
2e450 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
2e460 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
2e470 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
2e480 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2e490 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
2e4a0 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
2e4b0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
2e4c0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
2e4d0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
2e4e0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
2e4f0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2e500 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
2e510 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
2e520 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
2e530 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
2e540 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
2e550 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
2e560 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
2e570 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
2e580 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
2e590 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
2e5a0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
2e5b0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2e5c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2e5d0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2e5e0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
2e5f0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
2e600 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
2e610 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
2e620 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
2e630 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
2e640 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
2e650 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
2e660 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2e670 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
2e680 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
2e690 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
2e6a0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2e6b0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
2e6c0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
2e6d0 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
2e6e0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
2e6f0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
2e700 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
2e710 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
2e720 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2e730 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
2e740 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
2e750 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
2e760 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
2e770 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2e780 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
2e790 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
2e7a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2e7b0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
2e7c0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
2e7d0 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
2e7e0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
2e7f0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
2e800 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
2e810 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
2e820 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
2e830 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
2e840 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2e850 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
2e860 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
2e870 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2e880 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
2e890 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
2e8a0 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
2e8b0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
2e8c0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2e8d0 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
2e8e0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
2e8f0 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
2e900 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </ol>.**.** <
2e910 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61  p>^sqlite3_prepa
2e920 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73 20  re_v3() differs 
2e930 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65  from sqlite3_pre
2e940 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69  pare_v2() only i
2e950 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20  n having.** the 
2e960 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73 20  extra prepFlags 
2e970 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68  parameter, which
2e980 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79 20   is a bit array 
2e990 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65  consisting of ze
2e9a0 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66  ro or.** more of
2e9b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45   the [SQLITE_PRE
2e9c0 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c  PARE_PERSISTENT|
2e9d0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a  SQLITE_PREPARE_*
2e9e0 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a  ] flags.  ^The.*
2e9f0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2ea00 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
2ea10 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74   works exactly t
2ea20 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
2ea30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2ea40 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70  () with a zero p
2ea50 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74  repFlags paramet
2ea60 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
2ea70 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
2ea80 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2ea90 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2eaa0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2eab0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2eac0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2ead0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2eae0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2eaf0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2eb00 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2eb10 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2eb20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2eb30 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2eb40 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2eb50 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2eb60 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2eb70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2eb80 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2eb90 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2eba0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2ebb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ebc0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2ebd0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2ebe0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2ebf0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2ec00 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2ec10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2ec20 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2ec30 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2ec40 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2ec50 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2ec60 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2ec70 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2ec80 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2ec90 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2eca0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2ecb0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2ecc0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2ecd0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2ece0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2ecf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2ed00 61 72 65 5f 76 33 28 0a 20 20 73 71 6c 69 74 65  are_v3(.  sqlite
2ed10 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2ed20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2ed30 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ed40 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2ed50 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2ed60 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2ed70 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2ed80 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2ed90 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2eda0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2edb0 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64  s. */.  unsigned
2edc0 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20   int prepFlags, 
2edd0 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  /* Zero or more 
2ede0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20  SQLITE_PREPARE_ 
2edf0 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74  flags */.  sqlit
2ee00 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2ee10 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2ee20 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2ee30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2ee40 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2ee50 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2ee60 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2ee70 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2ee80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
2ee90 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2eea0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2eeb0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2eec0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2eed0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2eee0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2eef0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2ef00 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2ef10 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2ef20 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2ef30 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2ef40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2ef50 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2ef60 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2ef70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2ef80 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2ef90 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2efa0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2efb0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2efc0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2efd0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
2efe0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2eff0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2f000 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2f010 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2f020 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2f030 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2f040 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2f050 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2f060 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2f070 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2f080 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2f090 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2f0a0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2f0b0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2f0c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2f0d0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2f0e0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2f0f0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2f100 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2f110 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2f120 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2f130 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2f140 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2f150 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2f160 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2f170 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2f180 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2f190 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2f1a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2f1b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2f1c0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2f1d0 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  .  unsigned int 
2f1e0 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65  prepFlags, /* Ze
2f1f0 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54  ro or more SQLIT
2f200 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73  E_PREPARE_ flags
2f210 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2f220 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2f230 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2f240 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2f250 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2f260 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2f270 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2f280 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2f290 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2f2a0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
2f2b0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
2f2c0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2f2d0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2f2e0 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2f2f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f300 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2f310 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46   copy of the UTF
2f320 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  -8.** SQL text u
2f330 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70  sed to create [p
2f340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f350 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a  t] P if P was.**
2f360 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c   created by [sql
2f370 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2f380 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
2f390 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b  pare_v3()],.** [
2f3a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2f3b0 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  6_v2()], or [sql
2f3c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2f3d0 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  3()]..** ^The sq
2f3e0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2f3f0 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  ql(P) interface 
2f400 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2f410 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20  r to a UTF-8.** 
2f420 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
2f430 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f  g the SQL text o
2f440 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2f450 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b  ment P with.** [
2f460 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2f470 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 20 5e  ] expanded..** ^
2f480 54 68 65 20 73 71 6c 69 74 65 33 5f 6e 6f 72 6d  The sqlite3_norm
2f490 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29 20 69 6e  alized_sql(P) in
2f4a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2f4b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55  a pointer to a U
2f4c0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63  TF-8.** string c
2f4d0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 6f  ontaining the no
2f4e0 72 6d 61 6c 69 7a 65 64 20 53 51 4c 20 74 65 78  rmalized SQL tex
2f4f0 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74  t of prepared st
2f500 61 74 65 6d 65 6e 74 20 50 2e 20 20 54 68 65 0a  atement P.  The.
2f510 2a 2a 20 73 65 6d 61 6e 74 69 63 73 20 75 73 65  ** semantics use
2f520 64 20 74 6f 20 6e 6f 72 6d 61 6c 69 7a 65 20 61  d to normalize a
2f530 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
2f540 72 65 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  re unspecified a
2f550 6e 64 20 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f  nd subject.** to
2f560 20 63 68 61 6e 67 65 2e 20 20 41 74 20 61 20 6d   change.  At a m
2f570 69 6e 69 6d 75 6d 2c 20 6c 69 74 65 72 61 6c 20  inimum, literal 
2f580 76 61 6c 75 65 73 20 77 69 6c 6c 20 62 65 20 72  values will be r
2f590 65 70 6c 61 63 65 64 20 77 69 74 68 20 73 75 69  eplaced with sui
2f5a0 74 61 62 6c 65 0a 2a 2a 20 70 6c 61 63 65 68 6f  table.** placeho
2f5b0 6c 64 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  lders..**.** ^(F
2f5c0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2f5d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2f5e0 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75  ent is created u
2f5f0 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20  sing the SQL.** 
2f600 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62  text "SELECT $ab
2f610 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70  c,:xyz" and if p
2f620 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73  arameter $abc is
2f630 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65   bound to intege
2f640 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61  r 2345.** and pa
2f650 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20  rameter :xyz is 
2f660 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71  unbound, then sq
2f670 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c  lite3_sql() will
2f680 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f   return.** the o
2f690 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20  riginal string, 
2f6a0 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2f6b0 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65  z" but sqlite3_e
2f6c0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a  xpanded_sql().**
2f6d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45   will return "SE
2f6e0 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e  LECT 2345,NULL".
2f6f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2f700 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2f710 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ql() interface r
2f720 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
2f730 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
2f740 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62  ry.** is availab
2f750 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  le to hold the r
2f760 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65  esult, or if the
2f770 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78   result would ex
2f780 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20  ceed the.** the 
2f790 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c  maximum string l
2f7a0 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64  ength determined
2f7b0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
2f7c0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  LIMIT_LENGTH]..*
2f7d0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
2f7e0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
2f7f0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
2f800 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74   option limits t
2f810 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f  he size of.** bo
2f820 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78  und parameter ex
2f830 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20  pansions.  ^The 
2f840 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41  [SQLITE_OMIT_TRA
2f850 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
2f860 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65  .** option cause
2f870 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  s sqlite3_expand
2f880 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61  ed_sql() to alwa
2f890 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  ys return NULL..
2f8a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  **.** ^The strin
2f8b0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
2f8c0 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 61 6e  qlite3_sql(P) an
2f8d0 64 20 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c  d sqlite3_normal
2f8e0 69 7a 65 64 5f 73 71 6c 28 50 29 0a 2a 2a 20 61  ized_sql(P).** a
2f8f0 72 65 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51  re managed by SQ
2f900 4c 69 74 65 20 61 6e 64 20 61 72 65 20 61 75 74  Lite and are aut
2f910 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64  omatically freed
2f920 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   when the prepar
2f930 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2f940 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a  is finalized..**
2f950 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74   ^The string ret
2f960 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2f970 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2f980 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68  , on the other h
2f990 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69  and,.** is obtai
2f9a0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2f9b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
2f9c0 6d 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20  must be free by 
2f9d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  the application.
2f9e0 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74  ** by passing it
2f9f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
2fa00 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  e()]..*/.const c
2fa10 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
2fa20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2fa30 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  Stmt);.char *sql
2fa40 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2fa50 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
2fa60 70 53 74 6d 74 29 3b 0a 63 6f 6e 73 74 20 63 68  pStmt);.const ch
2fa70 61 72 20 2a 73 71 6c 69 74 65 33 5f 6e 6f 72 6d  ar *sqlite3_norm
2fa80 61 6c 69 7a 65 64 5f 73 71 6c 28 73 71 6c 69 74  alized_sql(sqlit
2fa90 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2faa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fab0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2fac0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2fad0 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2fae0 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
2faf0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2fb00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2fb10 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
2fb20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2fb30 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2fb40 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
2fb50 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
2fb60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
2fb70 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
2fb80 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
2fb90 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2fba0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2fbb0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
2fbc0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2fbd0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2fbe0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
2fbf0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
2fc00 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2fc10 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
2fc20 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
2fc30 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
2fc40 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
2fc50 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
2fc60 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
2fc70 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
2fc80 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
2fc90 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
2fca0 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
2fcb0 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
2fcc0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2fcd0 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
2fce0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
2fcf0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2fd00 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
2fd10 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
2fd20 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
2fd30 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2fd40 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
2fd50 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
2fd60 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2fd70 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
2fd80 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2fd90 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
2fda0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2fdb0 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
2fdc0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
2fdd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
2fde0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
2fdf0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
2fe00 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
2fe10 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
2fe20 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
2fe30 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
2fe40 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
2fe50 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2fe60 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
2fe70 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
2fe80 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
2fe90 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
2fea0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2feb0 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
2fec0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
2fed0 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
2fee0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
2fef0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
2ff00 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
2ff10 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
2ff20 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
2ff30 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
2ff40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2ff50 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2ff60 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
2ff70 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2ff80 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2ff90 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2ffa0 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2ffb0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2ffc0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2ffd0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2ffe0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2fff0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
30000 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73   disk..** ^The s
30010 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
30020 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65  only() interface
30030 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f   returns true fo
30040 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a  r [BEGIN] since.
30050 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c  ** [BEGIN] merel
30060 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20  y sets internal 
30070 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b  flags, but the [
30080 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45  BEGIN|BEGIN IMME
30090 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42  DIATE] and.** [B
300a0 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55  EGIN|BEGIN EXCLU
300b0 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64  SIVE] commands d
300c0 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61  o touch the data
300d0 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73  base and so.** s
300e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
300f0 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66  only() returns f
30100 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63  alse for those c
30110 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20  ommands..*/.int 
30120 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
30130 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
30140 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
30160 72 79 20 54 68 65 20 45 58 50 4c 41 49 4e 20 53  ry The EXPLAIN S
30170 65 74 74 69 6e 67 20 46 6f 72 20 41 20 50 72 65  etting For A Pre
30180 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
30190 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
301a0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
301b0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
301c0 69 73 65 78 70 6c 61 69 6e 28 53 29 20 69 6e 74  isexplain(S) int
301d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31  erface returns 1
301e0 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 65 70 61   if the.** prepa
301f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 53 20  red statement S 
30200 69 73 20 61 6e 20 45 58 50 4c 41 49 4e 20 73 74  is an EXPLAIN st
30210 61 74 65 6d 65 6e 74 2c 20 6f 72 20 32 20 69 66  atement, or 2 if
30220 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
30230 74 20 53 20 69 73 20 61 6e 20 45 58 50 4c 41 49  t S is an EXPLAI
30240 4e 20 51 55 45 52 59 20 50 4c 41 4e 2e 0a 2a 2a  N QUERY PLAN..**
30250 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
30260 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28 53 29 20  mt_isexplain(S) 
30270 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30280 73 20 30 20 69 66 20 53 20 69 73 0a 2a 2a 20 61  s 0 if S is.** a
30290 6e 20 6f 72 64 69 6e 61 72 79 20 73 74 61 74 65  n ordinary state
302a0 6d 65 6e 74 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ment or a NULL p
302b0 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  ointer..*/.int s
302c0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 69 73 65 78  qlite3_stmt_isex
302d0 70 6c 61 69 6e 28 73 71 6c 69 74 65 33 5f 73 74  plain(sqlite3_st
302e0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
302f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
30300 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
30310 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
30320 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
30330 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
30340 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
30350 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
30360 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
30370 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
30380 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
30390 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
303a0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
303b0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
303c0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
303d0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
303e0 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74  S)] but has neit
303f0 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  her run to compl
30400 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a  etion (returned.
30410 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
30420 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
30430 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20  tep(S)]) nor.** 
30440 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
30450 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30460 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
30470 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
30480 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
30490 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
304a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
304b0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
304c0 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
304d0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
304e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
304f0 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
30500 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
30510 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
30520 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
30530 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
30540 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
30550 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
30560 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
30570 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
30580 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
30590 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
305a0 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
305b0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
305c0 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
305d0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
305e0 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
305f0 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
30600 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
30610 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
30620 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
30630 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
30640 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
30650 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
30660 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
30670 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
30680 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
30690 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
306a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
306b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
306c0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
306d0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
306e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
306f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30700 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
30710 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30720 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
30730 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
30740 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
30750 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
30760 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
30770 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
30780 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
30790 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
307a0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
307b0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
307c0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
307d0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
307e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
307f0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
30800 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
30810 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
30820 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
30830 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
30840 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
30850 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
30860 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
30870 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
30880 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
30890 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
308a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
308b0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
308c0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
308d0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
308e0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
308f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
30900 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
30910 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
30920 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
30930 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
30940 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
30950 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
30960 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
30970 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30980 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  alue.  The.** [s
30990 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
309a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  ()] interface ca
309b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e  n be used to con
309c0 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a  struct a new .**
309d0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
309e0 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  e3_value from an
309f0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
30a00 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
30a10 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
30a20 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
30a30 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
30a40 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
30a50 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
30a60 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
30a70 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
30a80 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
30a90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
30aa0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
30ab0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
30ac0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
30ad0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
30ae0 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
30af0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
30b00 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
30b10 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
30b20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
30b30 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
30b40 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
30b50 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
30b60 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
30b70 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
30b80 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
30b90 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
30ba0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
30bb0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
30bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
30bd0 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
30be0 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
30bf0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
30c00 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
30c10 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
30c20 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
30c30 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
30c40 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
30c50 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
30c60 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
30c70 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
30c80 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
30c90 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
30ca0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
30cb0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
30cc0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
30cd0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
30ce0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
30cf0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
30d00 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
30d10 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
30d20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30d30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
30d40 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
30d50 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
30d60 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
30d70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
30d80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30d90 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
30da0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
30db0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30dc0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
30dd0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
30de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
30df0 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
30e00 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
30e10 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30e20 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
30e30 6e 6c 79 20 62 65 20 75 73 65 64 20 61 73 20 61  nly be used as a
30e40 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b  rguments.** to [
30e50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
30e60 61 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  alue()], [sqlite
30e70 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2c  3_bind_value()],
30e80 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
30e90 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 2a  _value_dup()]..*
30ea0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
30eb0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
30ec0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
30ed0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
30ee0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
30ef0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
30f00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
30f10 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
30f20 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  ruct sqlite3_val
30f30 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ue sqlite3_value
30f40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30f50 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
30f60 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
30f70 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
30f80 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
30f90 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
30fa0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
30fb0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
30fc0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
30fd0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
30fe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
30ff0 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
31000 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
31010 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
31020 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
31030 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
31040 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31050 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
31060 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
31070 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
31080 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
31090 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
310a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
310b0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
310c0 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
310d0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
310e0 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
310f0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
31100 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
31110 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
31120 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
31130 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
31140 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
31150 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
31160 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
31170 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
31180 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
31190 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
311a0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
311b0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
311c0 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
311d0 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
311e0 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
311f0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
31200 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
31210 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
31220 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
31230 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
31240 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
31250 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ing}.** METHOD: 
31260 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
31270 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
31280 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
31290 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
312a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
312b0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
312c0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
312d0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
312e0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
312f0 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
31300 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
31310 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
31320 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
31330 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
31340 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
31350 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
31360 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
31370 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
31380 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
31390 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
313a0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
313b0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
313c0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
313d0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
313e0 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
313f0 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
31400 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
31410 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
31420 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
31430 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
31440 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
31450 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
31460 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
31470 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
31480 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
31490 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
314a0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
314b0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
314c0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
314d0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
314e0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
314f0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
31500 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
31510 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
31520 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
31530 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
31540 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
31550 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
31560 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
31570 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
31580 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
31590 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
315a0 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
315b0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
315c0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
315d0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
315e0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
315f0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
31600 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
31610 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
31620 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
31630 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
31640 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
31650 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
31660 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
31670 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
31680 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
31690 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
316a0 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
316b0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
316c0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
316d0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
316e0 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
316f0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
31700 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
31710 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
31720 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
31730 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
31740 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
31750 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
31760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
31770 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
31780 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
31790 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
317a0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
317b0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
317c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
317d0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
317e0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
317f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
31800 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c  _blob() is a NUL
31810 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
31820 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
31830 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65  ter.** is ignore
31840 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65  d and the end re
31850 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65  sult is the same
31860 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   as sqlite3_bind
31870 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  _null()..**.** ^
31880 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
31890 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
318a0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
318b0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
318c0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
318d0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
318e0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
318f0 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
31900 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
31910 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
31920 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
31930 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
31940 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
31950 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
31960 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
31970 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
31980 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
31990 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e  text16().** is n
319a0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
319b0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
319c0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
319d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
319e0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
319f0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
31a00 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
31a10 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
31a20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
31a30 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c  b() is negative,
31a40 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68   then.** the beh
31a50 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
31a60 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  ed..** If a non-
31a70 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
31a80 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
31a90 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
31aa0 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
31ab0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
31ac0 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69  text16() or sqli
31ad0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
31ae0 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70  ) then.** that p
31af0 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
31b00 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
31b10 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55  .** where the NU
31b20 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
31b30 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e  ld occur assumin
31b40 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72  g the string wer
31b50 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61  e NUL.** termina
31b60 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
31b70 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
31b80 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74  r at byte offset
31b90 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20  s less than .** 
31ba0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
31bb0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
31bc0 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  r then the resul
31bd0 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75  ting string valu
31be0 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69  e will.** contai
31bf0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e  n embedded NULs.
31c00 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20    The result of 
31c10 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f  expressions invo
31c20 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a  lving strings.**
31c30 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
31c40 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
31c50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
31c60 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
31c70 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69  he BLOB and stri
31c80 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72  ng binding inter
31c90 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65  faces.** is a de
31ca0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
31cb0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
31cc0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
31cd0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
31ce0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
31cf0 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
31d00 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
31d10 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
31d20 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
31d30 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
31d40 63 61 6c 6c 20 74 6f 20 74 68 65 20 62 69 6e 64  call to the bind
31d50 20 41 50 49 20 66 61 69 6c 73 2c 0a 2a 2a 20 65   API fails,.** e
31d60 78 63 65 70 74 20 74 68 65 20 64 65 73 74 72 75  xcept the destru
31d70 63 74 6f 72 20 69 73 20 6e 6f 74 20 63 61 6c 6c  ctor is not call
31d80 65 64 20 69 66 20 74 68 65 20 74 68 69 72 64 20  ed if the third 
31d90 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e  parameter is a N
31da0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
31db0 72 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  r the fourth par
31dc0 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
31dd0 76 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ve..** ^If the f
31de0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
31df0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
31e00 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
31e10 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
31e20 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
31e30 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
31e40 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
31e50 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
31e60 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
31e70 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
31e80 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
31e90 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
31ea0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
31eb0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
31ec0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
31ed0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
31ee0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
31ef0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
31f00 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
31f10 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
31f20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
31f30 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20  *.** ^The sixth 
31f40 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
31f50 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
31f60 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
31f70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
31f80 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
31f90 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
31fa0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
31fb0 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73  UTF16LE].** to s
31fc0 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64  pecify the encod
31fd0 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20  ing of the text 
31fe0 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
31ff0 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74  ameter.  If.** t
32000 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
32010 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
32020 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f  d_text64() is no
32030 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
32040 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73  allowed values s
32050 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69  hown above, or i
32060 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  f the text encod
32070 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
32080 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63  .** from the enc
32090 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20  oding specified 
320a0 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72  by the sixth par
320b0 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
320c0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
320d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
320e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
320f0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
32100 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
32110 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
32120 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
32130 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
32140 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
32150 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
32160 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
32170 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
32180 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
32190 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
321a0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
321b0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
321c0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
321d0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
321e0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
321f0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
32200 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
32210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
32220 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
32230 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
32240 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
32250 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
32260 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
32270 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
32280 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
32290 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
322a0 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c  _bind_pointer(S,
322b0 49 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65  I,P,T,D) routine
322c0 20 63 61 75 73 65 73 20 74 68 65 20 49 2d 74 68   causes the I-th
322d0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a   parameter in.**
322e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
322f0 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20  ment] S to have 
32300 61 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20  an SQL value of 
32310 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73  NULL, but to als
32320 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74  o be.** associat
32330 65 64 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e  ed with the poin
32340 74 65 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e  ter P of type T.
32350 20 20 5e 44 20 69 73 20 65 69 74 68 65 72 20 61    ^D is either a
32360 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
32370 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
32380 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75   a destructor fu
32390 6e 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53  nction for P. ^S
323a0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
323b0 65 20 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63  e the.** destruc
323c0 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e  tor D with a sin
323d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
323e0 50 20 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e  P when it is fin
323f0 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50  ished using.** P
32400 2e 20 20 54 68 65 20 54 20 70 61 72 61 6d 65 74  .  The T paramet
32410 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73  er should be a s
32420 74 61 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72  tatic string, pr
32430 65 66 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e  eferably a strin
32440 67 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68  g.** literal. Th
32450 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
32460 6f 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65  ointer() routine
32470 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   is part of the.
32480 2a 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73  ** [pointer pass
32490 69 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61  ing interface] a
324a0 64 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20  dded for SQLite 
324b0 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49  3.20.0..**.** ^I
324c0 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
324d0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
324e0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
324f0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
32500 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
32510 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32520 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
32530 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32540 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
32550 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
32560 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
32570 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
32580 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
32590 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
325a0 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
325b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
325c0 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
325d0 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
325e0 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
325f0 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
32600 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
32610 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
32620 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
32630 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
32640 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
32650 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
32660 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
32670 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
32680 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
32690 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
326a0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
326b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
326c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
326d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
326e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
326f0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
32700 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
32710 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
32720 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
32730 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
32740 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65  TOOBIG] might be
32750 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
32760 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e   size of a strin
32770 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63  g or BLOB.** exc
32780 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f  eeds limits impo
32790 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
327a0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
327b0 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72  IMIT_LENGTH]) or
327c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
327d0 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51  LENGTH]..** ^[SQ
327e0 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
327f0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
32800 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
32810 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
32820 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
32830 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
32840 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
32850 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
32860 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
32870 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
32880 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
32890 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
328a0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
328b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
328c0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
328d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
328e0 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
328f0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
32900 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
32910 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
32920 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
32930 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
32940 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
32950 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
32960 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
32970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32980 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
32990 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
329a0 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
329b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
329c0 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
329d0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
329e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
329f0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
32a00 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
32a10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32a20 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
32a30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
32a40 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
32a50 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
32a60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
32a70 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
32a80 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
32a90 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69  ,int,void(*)(voi
32aa0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
32ab0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
32ac0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32ad0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
32ae0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
32af0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
32b00 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c  _bind_text64(sql
32b10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
32b20 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
32b30 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
32b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32b50 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
32b60 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20  oid*), unsigned 
32b70 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a  char encoding);.
32b80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
32b90 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
32ba0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
32bb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
32bc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
32bd0 6e 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74  nd_pointer(sqlit
32be0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76  e3_stmt*, int, v
32bf0 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
32c00 2a 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  *,void(*)(void*)
32c10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
32c20 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
32c30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
32c40 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c   int n);.int sql
32c50 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
32c60 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
32c70 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
32c80 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  _uint64);../*.**
32c90 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
32ca0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
32cb0 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ers.** METHOD: s
32cc0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32cd0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
32ce0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
32cf0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
32d00 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
32d10 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
32d20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
32d30 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
32d40 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
32d50 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
32d60 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
32d70 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
32d80 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
32d90 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
32da0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
32db0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
32dc0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
32dd0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
32de0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
32df0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
32e00 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
32e10 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
32e20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
32e30 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
32e40 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
32e50 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
32e60 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
32e70 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
32e80 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
32e90 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
32ea0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
32eb0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
32ec0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
32ed0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
32ee0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
32ef0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
32f00 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
32f10 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
32f20 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
32f30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
32f40 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
32f50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
32f60 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
32f70 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
32f80 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
32f90 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
32fa0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
32fb0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
32fc0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
32fd0 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  er.** METHOD: sq
32fe0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
32ff0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
33000 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
33010 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
33020 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
33030 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
33040 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
33050 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
33060 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
33070 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
33080 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
33090 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
330a0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
330b0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
330c0 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
330d0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
330e0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
330f0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
33100 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
33110 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
33120 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
33130 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
33140 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
33150 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
33160 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
33170 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
33180 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
33190 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
331a0 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
331b0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
331c0 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
331d0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
331e0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
331f0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
33200 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
33210 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
33220 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
33230 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
33240 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
33250 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
33260 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
33270 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
33280 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
33290 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
332a0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
332b0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
332c0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
332d0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
332e0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
332f0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
33300 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
33310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33320 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
33330 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
33340 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
33350 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
33360 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
33370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
33380 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
33390 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
333a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
333b0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
333c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
333d0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
333e0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
333f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
33400 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
33410 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
33420 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33430 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
33440 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
33450 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48  ven Name.** METH
33460 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
33470 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
33480 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
33490 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
334a0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
334b0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
334c0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
334d0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
334e0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
334f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
33500 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
33510 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
33520 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
33530 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
33540 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
33550 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
33560 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
33570 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
33580 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
33590 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
335a0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
335b0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
335c0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
335d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
335e0 65 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  e16_v2()] or.** 
335f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33600 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v3()]..**.** 
33610 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
33620 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
33630 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
33640 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
33650 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
33660 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
33670 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
33680 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  r_name()]..*/.in
33690 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
336a0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
336b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
336c0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
336d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
336e0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
336f0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
33700 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
33710 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33720 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  _stmt.**.** ^Con
33730 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
33740 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
33750 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33760 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
33770 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
33780 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
33790 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
337a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
337b0 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
337c0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
337d0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
337e0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
337f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
33800 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
33810 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
33820 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
33830 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
33840 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
33850 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33860 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
33870 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
33880 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
33890 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
338a0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
338b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
338c0 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f  nt]. ^If this ro
338d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c  utine returns 0,
338e0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
338f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
33900 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73  atement] returns
33910 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78   no data (for ex
33920 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
33930 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c  ])..** ^However,
33940 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 74 68   just because th
33950 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
33960 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75  ns a positive nu
33970 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  mber does not.**
33980 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f   mean that one o
33990 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64  r more rows of d
339a0 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75  ata will be retu
339b0 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54  rned.  ^A SELECT
339c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69   statement.** wi
339d0 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20 61  ll always have a
339e0 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65   positive sqlite
339f0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
33a00 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f   but depending o
33a10 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63  n the.** WHERE c
33a20 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
33a30 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20  s and the table 
33a40 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68  content, it migh
33a50 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73  t return no rows
33a60 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
33a70 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
33a80 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
33a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
33aa0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
33ab0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
33ac0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
33ad0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
33ae0 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
33af0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
33b00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
33b10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
33b20 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
33b30 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
33b40 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
33b50 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
33b60 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
33b70 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
33b80 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
33b90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
33ba0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
33bb0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
33bc0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
33bd0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
33be0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
33bf0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
33c00 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
33c10 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
33c20 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
33c30 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
33c40 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
33c50 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
33c60 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
33c70 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
33c80 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
33c90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
33ca0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
33cb0 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
33cc0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
33cd0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
33ce0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
33cf0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
33d00 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
33d10 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
33d20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
33d30 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
33d40 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33d50 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
33d60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
33d70 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
33d80 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
33d90 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
33da0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
33db0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
33dc0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
33dd0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
33de0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
33df0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
33e00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
33e10 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
33e20 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
33e30 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
33e40 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
33e50 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
33e60 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
33e70 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
33e80 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
33e90 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
33ea0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
33eb0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
33ec0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
33ed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
33ee0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
33ef0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
33f00 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
33f10 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
33f20 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
33f30 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
33f40 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
33f50 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
33f60 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
33f70 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
33f80 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
33f90 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
33fa0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
33fb0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
33fc0 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
33fd0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
33fe0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
33ff0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
34000 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
34010 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
34020 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
34030 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
34040 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
34050 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
34060 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
34070 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
34080 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
34090 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
340a0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
340b0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
340c0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
340d0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
340e0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
340f0 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
34100 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
34110 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
34120 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
34130 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
34140 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
34150 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
34160 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
34170 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
34180 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
34190 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
341a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
341b0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
341c0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
341d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
341e0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
341f0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
34200 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
34210 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
34220 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
34230 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
34240 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
34250 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34260 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
34270 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
34280 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
34290 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
342a0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
342b0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
342c0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
342d0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
342e0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
342f0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
34300 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
34310 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
34320 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
34330 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
34340 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
34350 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
34360 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
34370 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
34380 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
34390 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
343a0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
343b0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
343c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
343d0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
343e0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
343f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
34400 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
34410 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
34420 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
34430 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
34440 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
34450 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
34460 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
34470 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
34480 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
34490 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
344a0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
344b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
344c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
344d0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
344e0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
344f0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
34500 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
34510 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
34520 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
34530 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
34540 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
34550 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
34560 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
34570 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
34580 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
34590 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
345a0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
345b0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
345c0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
345d0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
345e0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
345f0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
34600 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
34610 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
34620 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
34630 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
34640 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
34650 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
34660 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
34670 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
34680 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
34690 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
346a0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
346b0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
346c0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
346d0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
346e0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
346f0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
34700 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
34710 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
34720 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
34730 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
34740 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
34750 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
34760 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
34770 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
34780 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
34790 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
347a0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
347b0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
347c0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
347d0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
347e0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
347f0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
34800 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
34810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
34820 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
34830 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
34840 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
34850 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
34860 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
34870 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
34880 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
34890 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
348a0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
348b0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
348c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
348d0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
348e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
348f0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
34900 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
34910 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
34920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
34930 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
34940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34950 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
34960 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
34970 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
34980 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
34990 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
349a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
349b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
349c0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
349d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
349e0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
349f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
34a00 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
34a10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
34a20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34a30 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
34a40 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
34a50 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
34a60 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
34a70 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
34a80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
34a90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34aa0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
34ab0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
34ac0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
34ad0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
34ae0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
34af0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
34b00 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
34b10 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
34b20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
34b30 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
34b40 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
34b50 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
34b60 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
34b70 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
34b80 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
34b90 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
34ba0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
34bb0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
34bc0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
34bd0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
34be0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
34bf0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
34c00 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
34c10 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
34c20 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
34c30 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
34c40 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
34c50 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
34c60 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
34c70 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
34c80 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
34c90 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
34ca0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
34cb0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
34cc0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
34cd0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
34ce0 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
34cf0 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
34d00 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
34d10 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
34d20 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
34d30 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
34d40 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
34d50 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
34d60 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
34d70 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
34d80 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
34d90 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
34da0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
34db0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
34dc0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
34dd0 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
34de0 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
34df0 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
34e00 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
34e10 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
34e20 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
34e30 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
34e40 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
34e50 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
34e60 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
34e70 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
34e80 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
34e90 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
34ea0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
34eb0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
34ec0 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
34ed0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
34ee0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
34ef0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
34f00 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
34f10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
34f20 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
34f30 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
34f40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
34f50 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
34f60 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
34f70 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
34f80 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
34f90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34fa0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
34fb0 72 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66  red using any of
34fc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
34fd0 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
34fe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
34ff0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
35000 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a  pare16_v2()],.**
35010 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
35020 70 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20  pare16_v3()] or 
35030 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
35040 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
35050 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35060 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
35070 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
35080 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
35090 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
350a0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
350b0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
350c0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
350d0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
350e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
350f0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
35100 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
35110 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
35120 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
35130 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
35140 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 58  ng the newer "vX
35150 22 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  " interfaces.** 
35160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35170 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
35180 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
35190 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
351a0 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71  16_v3()],.** [sq
351b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
351c0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
351d0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
351e0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
351f0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
35200 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35210 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
35220 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
35230 58 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  X" interface is 
35240 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
35250 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
35260 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
35270 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
35280 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
35290 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
352a0 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79  * ^In the legacy
352b0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
352c0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
352d0 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
352e0 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
352f0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
35300 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
35310 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
35320 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
35330 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22  * ^With the "v2"
35340 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
35350 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
35360 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
35370 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
35380 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
35390 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
353a0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ell..**.** ^[SQL
353b0 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
353c0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
353d0 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
353e0 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
353f0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
35400 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
35410 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49   do its job.  ^I
35420 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
35430 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
35440 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
35450 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
35460 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
35470 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
35480 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
35490 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
354a0 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
354b0 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
354c0 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20  rs within an.** 
354d0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
354e0 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
354f0 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
35500 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
35510 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
35520 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
35530 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
35540 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
35550 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
35560 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
35570 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
35580 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
35590 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
355a0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
355b0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
355c0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
355d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
355e0 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
355f0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
35600 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
35610 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
35620 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
35630 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
35640 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
35650 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
35660 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
35670 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
35680 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
35690 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
356a0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
356b0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
356c0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
356d0 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
356e0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
356f0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
35700 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
35710 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
35720 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
35730 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
35740 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
35750 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
35760 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
35770 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
35780 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
35790 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
357a0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
357b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
357c0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
357d0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
357e0 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
357f0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
35800 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
35810 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
35820 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
35830 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
35840 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
35850 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
35860 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
35870 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
35880 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
35890 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
358a0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
358b0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
358c0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
358d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
358e0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
358f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35900 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
35910 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
35920 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
35930 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
35940 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
35950 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
35960 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
35970 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
35980 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
35990 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
359a0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
359b0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
359c0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
359d0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
359e0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
359f0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
35a00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
35a10 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
35a20 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
35a30 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
35a40 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
35a50 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
35a60 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
35a70 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
35a80 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
35a90 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
35aa0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
35ab0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
35ac0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
35ad0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
35ae0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
35af0 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f  * For all versio
35b00 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20  ns of SQLite up 
35b10 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
35b20 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c   3.6.23.1, a cal
35b30 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
35b40 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65  _reset()] was re
35b50 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c  quired after sql
35b60 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
35b70 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a  rned anything.**
35b80 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
35b90 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20  ITE_ROW] before 
35ba0 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
35bb0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
35bc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
35bd0 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65   Failure to rese
35be0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
35bf0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a  tatement using .
35c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
35c10 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c  t()] would resul
35c20 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
35c30 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
35c40 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  rom.** sqlite3_s
35c50 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
35c60 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  r [version 3.6.2
35c70 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e  3.1] ([dateof:3.
35c80 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69  6.23.1],.** sqli
35c90 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
35ca0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
35cb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
35cc0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
35cd0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
35ce0 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
35cf0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
35d00 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
35d10 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
35d20 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
35d30 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
35d40 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
35d50 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
35d60 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
35d70 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
35d80 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
35d90 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
35da0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
35db0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
35dc0 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
35dd0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
35de0 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
35df0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
35e00 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
35e10 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
35e20 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
35e30 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
35e40 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
35e50 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
35e60 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
35e70 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
35e80 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
35e90 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
35ea0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
35eb0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
35ec0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
35ed0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
35ee0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
35ef0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
35f00 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
35f10 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
35f20 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
35f30 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
35f40 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
35f50 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
35f60 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
35f70 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
35f80 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
35f90 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
35fa0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
35fb0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
35fc0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
35fd0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
35fe0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
35ff0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
36000 61 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71  are_v3()] or [sq
36010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
36020 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
36030 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
36040 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
36050 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69  repare16_v3()] i
36060 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
36070 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
36080 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
36090 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
360a0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
360b0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
360c0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
360d0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
360e0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
360f0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
36100 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
36110 66 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72  f the "vX" inter
36120 66 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65  faces is recomme
36130 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
36140 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
36150 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
36160 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
36170 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
36180 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  a result set.** 
36190 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
361a0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
361b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
361c0 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
361d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
361e0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
361f0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
36200 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
36210 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
36220 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
36230 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
36240 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
36250 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
36260 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
36270 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
36280 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
36290 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
362a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
362b0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
362c0 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
362d0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
362e0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
362f0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
36300 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
36310 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
36320 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
36330 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
36340 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
36350 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
36360 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
36370 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
36380 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
36390 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
363a0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
363b0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
363c0 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
363d0 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
363e0 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
363f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
36400 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
36410 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
36420 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
36430 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
36440 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
36450 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
36460 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
36470 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
36480 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
36490 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
364a0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
364b0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
364c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
364d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
364e0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
364f0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
36500 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
36510 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
36520 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
36530 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
36540 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
36550 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
36560 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
36570 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
36580 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
36590 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
365a0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
365b0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
365c0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
365d0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
365e0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
365f0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
36600 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
36610 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
36620 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
36630 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
36640 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
36650 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
36660 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
36670 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
36680 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
36690 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
366a0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
366b0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
366c0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
366d0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
366e0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
366f0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
36700 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
36710 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
36720 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
36730 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
36740 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
36750 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
36760 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
36770 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
36780 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
36790 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
367a0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
367b0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
367c0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
367d0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
367e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
367f0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
36800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
36810 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
36820 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
36830 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
36840 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
36850 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
36860 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
36870 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
36880 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53  _stmt.**.** <b>S
36890 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c  ummary:</b>.** <
368a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c  blockquote><tabl
368b0 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70  e border=0 cellp
368c0 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61  adding=0 cellspa
368d0 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c  cing=0>.** <tr><
368e0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
368f0 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64  lumn_blob</b><td
36900 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20  >&rarr;<td>BLOB 
36910 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
36920 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
36930 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74  umn_double</b><t
36940 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c  d>&rarr;<td>REAL
36950 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
36960 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
36970 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e  lumn_int</b><td>
36980 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74  &rarr;<td>32-bit
36990 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a   INTEGER result.
369a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
369b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
369c0 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  64</b><td>&rarr;
369d0 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47  <td>64-bit INTEG
369e0 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
369f0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
36a00 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c  column_text</b><
36a10 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
36a20 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a  -8 TEXT result.*
36a30 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
36a40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36a50 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  16</b><td>&rarr;
36a60 3c 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20  <td>UTF-16 TEXT 
36a70 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
36a80 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
36a90 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64  umn_value</b><td
36aa0 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72  >&rarr;<td>The r
36ab0 65 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20  esult as an .** 
36ac0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75  [sqlite3_value|u
36ad0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
36ae0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36af0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62  ..** <tr><td>&nb
36b00 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  sp;<td>&nbsp;<td
36b10 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c  >&nbsp;.** <tr><
36b20 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
36b30 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74  lumn_bytes</b><t
36b40 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65  d>&rarr;<td>Size
36b50 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72   of a BLOB.** or
36b60 20 61 20 55 54 46 2d 38 20 54 45 58 54 20 72 65   a UTF-8 TEXT re
36b70 73 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a  sult in bytes.**
36b80 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
36b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36ba0 31 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f  16&nbsp;&nbsp;</
36bb0 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b  b>.** <td>&rarr;
36bc0 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e  &nbsp;&nbsp;<td>
36bd0 53 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a  Size of UTF-16.*
36be0 2a 20 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a  * TEXT in bytes.
36bf0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
36c00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
36c10 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
36c20 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61  td>Default.** da
36c30 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65  tatype of the re
36c40 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  sult.** </table>
36c50 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
36c60 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c  .** <b>Details:<
36c70 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  /b>.**.** ^These
36c80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
36c90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
36ca0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
36cb0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
36cc0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
36cd0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
36ce0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
36cf0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
36d00 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
36d10 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
36d20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
36d30 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
36d40 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
36d50 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
36d60 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
36d70 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
36d80 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
36d90 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
36da0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
36db0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
36dc0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
36dd0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
36de0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
36df0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
36e00 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
36e10 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
36e20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
36e30 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
36e40 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
36e50 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
36e60 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
36e70 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
36e80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
36e90 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
36ea0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
36eb0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
36ec0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
36ed0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
36ee0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
36ef0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
36f00 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
36f10 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
36f20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
36f30 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
36f40 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
36f50 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
36f60 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
36f70 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
36f80 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
36f90 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
36fa0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
36fb0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
36fc0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
36fd0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
36fe0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
36ff0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
37000 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
37010 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
37020 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
37030 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37040 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
37050 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
37060 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
37070 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
37080 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
37090 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
370a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
370b0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
370c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
370d0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
370e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
370f0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
37100 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
37110 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
37120 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
37130 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
37140 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
37150 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
37160 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
37170 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 73  t six interfaces
37180 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65   (_blob, _double
37190 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20  , _int, _int64, 
371a0 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74  _text, and _text
371b0 31 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75  16).** each retu
371c0 72 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  rn the value of 
371d0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
371e0 69 6e 20 61 20 73 70 65 63 69 66 69 63 20 64 61  in a specific da
371f0 74 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a  ta format.  If.*
37200 2a 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  * the result col
37210 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69  umn is not initi
37220 61 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75  ally in the requ
37230 65 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f  ested format (fo
37240 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66  r example,.** if
37250 20 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72   the query retur
37260 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75  ns an integer bu
37270 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  t the sqlite3_co
37280 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65  lumn_text() inte
37290 72 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64  rface.** is used
372a0 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20   to extract the 
372b0 76 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61  value) then an a
372c0 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
372d0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
372e0 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ormed..**.** ^Th
372f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
37300 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
37310 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
37320 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
37330 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
37340 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
37350 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
37360 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
37370 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
37380 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
37390 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
373a0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
373b0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
373c0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
373d0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
373e0 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65  NULL]..** The re
373f0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71  turn value of sq
37400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
37410 65 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20  e() can be used 
37420 74 6f 20 64 65 63 69 64 65 20 77 68 69 63 68 0a  to decide which.
37430 2a 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  ** of the first 
37440 73 69 78 20 69 6e 74 65 72 66 61 63 65 20 73 68  six interface sh
37450 6f 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20  ould be used to 
37460 65 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75  extract the colu
37470 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65  mn value..** The
37480 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
37490 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
374a0 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
374b0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
374c0 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74  o.** automatic t
374d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
374e0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f  have occurred fo
374f0 72 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71  r the value in q
37500 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66  uestion.  .** Af
37510 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
37520 72 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c  rsion, the resul
37530 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c  t of calling sql
37540 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
37550 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ().** is undefin
37560 65 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c  ed, though harml
37570 65 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ess.  Future.** 
37580 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
37590 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
375a0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
375b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
375c0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
375d0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
375e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
375f0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
37600 42 20 6f 72 20 61 20 54 45 58 54 20 73 74 72 69  B or a TEXT stri
37610 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ng, then the sql
37620 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37630 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  s().** or sqlite
37640 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
37650 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 63 61  () interfaces ca
37660 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74  n be used to det
37670 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a  ermine the size.
37680 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20  ** of that BLOB 
37690 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  or string..**.**
376a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
376b0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
376c0 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
376d0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
376e0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
376f0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
37700 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
37710 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
37720 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
37730 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
37740 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
37750 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
37760 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
37770 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
37780 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
37790 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
377a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
377b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
377c0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
377d0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
377e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
377f0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
37800 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
37810 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
37820 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
37830 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
37840 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
37850 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
37860 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
37870 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
37880 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
37890 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
378a0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
378b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
378c0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
378d0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
378e0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
378f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
37900 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
37910 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
37920 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
37930 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
37940 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
37950 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
37960 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
37970 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
37980 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
37990 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
379a0 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
379b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
379c0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
379d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
379e0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
379f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
37a00 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
37a10 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
37a20 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
37a30 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
37a40 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
37a50 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
37a60 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
37a70 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
37a80 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
37a90 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
37aa0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
37ab0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
37ac0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
37ad0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
37ae0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
37af0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37b00 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
37b10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37b20 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
37b30 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
37b40 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
37b50 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
37b60 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
37b70 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
37b80 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
37b90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
37ba0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
37bb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37bc0 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
37bd0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
37be0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
37bf0 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
37c00 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
37c10 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
37c20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
37c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
37c40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
37c50 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
37c60 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
37c70 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
37c80 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
37c90 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
37ca0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
37cb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
37cc0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
37cd0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
37ce0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
37cf0 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f  ** <b>Warning:</
37d00 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  b> ^The object r
37d10 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
37d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
37d30 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
37d40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37d50 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
37d60 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65    In a multithre
37d70 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  aded environment
37d80 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63  ,.** an unprotec
37d90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
37da0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c  e object may onl
37db0 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79  y be used safely
37dc0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
37dd0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
37de0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
37df0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
37e00 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
37e10 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
37e20 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
37e30 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
37e40 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
37e50 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
37e60 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
37e70 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
37e80 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
37e90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37ea0 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
37eb0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
37ec0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
37ed0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
37ee0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e  he behavior is n
37ef0 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a  ot threadsafe..*
37f00 2a 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c  * Hence, the sql
37f10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
37f20 65 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  e() interface.**
37f30 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c   is normally onl
37f40 79 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20  y useful within 
37f50 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
37f60 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69  on of .** [appli
37f70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
37f80 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
37f90 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
37fa0 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a  ], not within.**
37fb0 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69   top-level appli
37fc0 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a  cation code..**.
37fd0 2a 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f 75  ** The these rou
37fe0 74 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70  tines may attemp
37ff0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
38000 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
38010 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72   result..** ^For
38020 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
38030 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
38040 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
38050 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
38060 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
38070 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
38080 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
38090 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
380a0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
380b0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
380c0 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
380d0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
380e0 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
380f0 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
38100 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
38110 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
38120 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
38130 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
38140 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
38150 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
38160 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
38170 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
38180 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
38190 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
381a0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
381b0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
381c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
381d0 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
381e0 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
381f0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
38200 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
38210 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
38220 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
38230 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
38240 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
38250 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
38260 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
38270 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
38280 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
38290 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
382a0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
382b0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
382c0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
382d0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
382e0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
382f0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
38300 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
38310 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
38320 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
38330 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
38340 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
38350 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
38360 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
38370 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
38380 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
38390 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
383a0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
383b0 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
383c0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
383d0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
383e0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
383f0 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
38400 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
38410 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
38420 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
38430 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
38440 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
38450 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
38460 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
38470 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
38480 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
38490 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
384a0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
384b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
384c0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
384d0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
384e0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
384f0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
38500 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
38510 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
38520 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
38530 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
38540 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
38550 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
38560 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
38570 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  te>)^.**.** Note
38580 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
38590 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
385a0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
385b0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
385c0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
385d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
385e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
385f0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
38600 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
38610 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
38620 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
38630 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
38640 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
38650 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
38660 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
38670 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
38680 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
38690 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
386a0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
386b0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
386c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
386d0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
386e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
386f0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
38700 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
38710 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
38720 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
38730 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
38740 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
38750 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
38760 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
38770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
38780 79 74 65 73 31 36 28 29 20 6f 72 0a 2a